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We're all teachers. 



I'M PLEASED THAT so many of you want to share your 
expertise with fellow readers. Since vve started our confer- 
ence on BIX (aw. tech journal, stop by), one of the most com- 
mon questions I see is "How can I write for the Tech ]ouma\l" 

The best way to start is to have a concrete idea and to 
draw up a rough outline of the article. Mail the outline 
along to me either by traditional means or via BIX 
(llaflamme) and include the article's projected length, a list 
of accompanying diagrams or listings, and a writing sam- 
ple. Be sure to mention your credentials and background in 
the cover letter. If we like the idea, I'll call and request the 
complete article and code. 

Remember, the Tech Journal's charter is to provide arti- 
cles and listings that teach-the reader how to better use the 
Amiga's unique capabilities. The stress is on Amiga; an 
introductory language piece will never make it beyond the 
"Thank you, but no thank you" bin. Past issues of the Tech 
journal, CATS' AmigaMail, and DevCon notes are good 
sources of inspiration. 

Don't get so busy writing, however, that you can't take 
time out for the 1991 North American Developers Confer- 
ence. Slated for September 4-7 at Colorado's Denver Mar- 
riott City Center, this year's conference should have a hill-to- 
bursting schedule of technical seminars, considering all the 
new hardware, 2.0, and CDTV developments. As tJiey were 
last year, marketing and public relations sessions are also on 
the agenda. Registered developers should receive registration 
forms and information automatically. If you haven't, contact 
CATS, 1200 Wilson Dr., West Chester, PA 19380. 

While CATS is educating the developers, the Amiga 
Developers' Association is rallying to educate the rest of the 
computing world about the Amiga's strengths. Under the 
leadership of a new board, the ADA is focusing on a single 
goal: to promote the Amiga to all that will listen. The first 
target is the computer press. As ammunition, the board will 
use position papers on the Amiga's benefits for users and 
developers. (Any potential authors out there?) The ADA 
also wants to pass along profiles of companies and individ- 
uals using the Amiga for innovative applications and 
unique situations. (If you are, promote yourself. Contact the 
ADA.) To offer your help, contact Chairperson Al Hospers 
al Dr. T's Music Software, 220 Boylston St. #306, Boston, 
MA 02167, If you'd like more general information or a 
membership application (dues are S150 per year), write to 
Treasurer Jerry Woiosenko, ADA Membership Drive, Psyg- 
nosis, 29 St. Mary's Court, Brookline, MA 02146. 

Whether educating programmers and engineers about 
the latest techniques and teclinologies or educating the 
world at large about the Amiga's power, we're all working 
for the same goal: to advance and expand the the Amiga 
market. Get in the game and help. ■ 
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ARexx Arcana: 
Hosts and Quotes 



By Marvin Weinslein 



EVERYONE AGREES AREXX (which is based on IBM's 

REXX> lets you harness the power of multitasking by relaying 
instructions between programs. A cloud of mystery and con- 
fusion, however, hovers over the concept of an ARexx host 
program. The number of ARexx-capable applications that can 
serve as ARexx hosts is large and growing rapidly. As a result, 
understanding ho\\' ARexx processes a command and passes 
it to a host is vital. The key to this is understanding ARexx's 
syntax and the way in which ARexx handles quotes. 

SYNTAX OVERVIEW 

Because a REXX command is defined in terms of what it is 
not, a lightning review of REXX syntax is in order. The sim- 
plest meaningful statement that can appear in a REXX pro- 
gram is a clause. The ARexx interpreter recognizes six types 

of clauses: 

A Comment 

A statement enclosed between a /* and its matching */, 
which is usually ignored by REXX. Every REXX program, 
however, must begin with a comment. (On IBM mainframes 
the comment was used to distinguish REXX programs from 
scripts written in IBM's EXEC language.) 

An Instruction 

A statement that begins with one of 32 keywords. The 32 
instructions, combined with assignment statements, define 
the skeleton of all REXX programs. They determine the man- 
ner and order in which things happen. For example, the SAY 
instruction causes ARexx to type a line of text to the CLI that 
launched the ARexx exec (program). 

/* beginning comment 7 
say hello 

produces: 
HELLO 

A Label 

A clause that consists of a single name followed by a colon, 
such as: 

START: 

You use labels to indicate the beginning of subroutines or. 



in special circumstances, to modify the flow of control in a 
REXX program. 

An Assignment 

Any clause of the form: 

name = expression 

where a variable name is followed by an = and an expression 

to be evaluated. 

A Null 

A blank line or a line containing only a semicolon. 

A Command 

Any clause that does not fall into one of the preceding cat- 
egories. When ARexx encounters a command clause it eval- 
uates the expression and then passes the result to an exter- 
nal host for further action. The externa! host may be either 
the native operating system or an application program de- 
signed to receive and act upon ARexx messages. You can 
modify the default host for an ARexx program using the 
ADDRESS instruction. A large portion of problems come 
from misunderstanding who the default host for a program 
is, and what limitations that host operates under. (More on 
this later.) 

The fact that REXX is typeless makes it easy to learn. No 
need to specify variables in advance; as far as REXX is con- 
cerned all variables are strings and defined, whether or not 
they have appeared on the left side of an assignment state- 
ment. If a variable has not been assigned a value, by default 
REXX assigns it the string obtained by uppercasing the vari- 
able's name. For example, it is REXX's job to figure out if the 
variable r in the statement: 

X = 4*r 

has a value for which the * operation is well defined. If r has 
not appeared in an assignment statement, REXX uppercases 
the r to obtain: 

X = 4*R 

and recognizes that it does not kno^v how to multiply a num- 
ber by a letter. The program then fails and produces an error 
message. 

Because the REXX interpreter treats all strings that do not 
contain blanks as possible variables, it automatically upper- 
cases text as it goes along. To tell ARexx not to examine a 
string for possible substitutions, we enclose it in matching 
single or double quotes. Thus, the program: 
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Avoid misquoting commands and the host trouble that follows 
hy learning some of ARexx's more esoteric facets. 



/"rexx:sayltrexx 

say Hello world 
say "Hello world" 
say 'Hello world' 
say "Hello" world 

produces the output: 

HELLO WORLD 
Hello world 
Hello world 
Hello WORLD 

Because you can use either single and double quotes, it is 
easy to include a quote inside a text string. For exarnple: 

/" rexx:quotetest.rexx 



say "Ttils Is an example of a string with a quota ' " 
say 'This is ar example of a string with a quote " ' 

produces the output: 

This Is an exaniple of a string with quote ' 
This Is an example of a string with a quote " 

Another mechanism for including a quote in a string is to 
type either " or "". In this case REXX eats the first quote and 
prints the second. For example: 

/"* rexxiescapetest.rexx 



say 'This is an example of a string with a quote " ' 

say "This Is an example of a string with a quote "$kern4pt" " 

produces the same output as the quotetest.rexx example. 

This simple discussion illustrates why quoting is used and 
the need for adopting a flexible set of quoting conventions. 
As long as you limit yourself to manipulating strings within 
ARexx programs, there is nothing more to know. Peculiari- 
ties arise, however, when you send strings containing quotes 
to an ARexx host. You must understand how ARexx pro- 
cesses a command line and the quoting conventions required 
by the host application to avoid problems caused when host 
applications use the same quoting characters as ARexx. 

COMMANDS AND HOSTS 

To guarantee that ARexx will immediately recognize a line 
as a command clause, you enclose it in quotes. In fact, the IBM 



REXX manual recommends this as good programming style. 
As an alternative, you could begin the line with a pair of 
matched quotes. For example, if an ARexx exec contains the 
following: 

""dtr 
"dir" 
dir 

ARexx instantly recognizes the first two lines as commands, 
but treats the third differently. First ARexx checks to see if dir 
is a built-in instruction. Because this test fails, ARexx next 
looks in the rexx: directory for a file named dir.rexx or dir. 
Not finding one, it passes dir to the default host to see if the 
host knows what to do with the command. 

Who is the default host for the program and will it know 
how to field this command? Things are starting to get com- 
plicated. The default host for an ARexx program depends 
upon how the ARexx program was launched. Even for pro- 
grams launched from a shell, there is a difference between 
those programs launched using rx and programs launched 
without using rx, from a truly ARexx-integrated shell. 

As ARexx arrived after the original Amiga CLI was devel- 
oped, it is not as well integrated into the CLI environment as 
REXX is on an IBM mainframe running VM/CMS. One triv- 
ial, but annoying, aspect of this lack of integration is that un- 
der AmigalX)S 1.3 you cannot launch an ARexx program by 
typing only its name. To run an ARexx program called 
myprog.rexx from a CLI (or Shell) you must type: 

rx myprog 

Under Amiga DOS 2.0 the situation is better, but not great. 
If you set the script bit for an ARexx program and add the 
file's directory to your path, you can execute the program by 
typing only the full name of the file, including the .rexx ex- 
tension. This is a minor annoyance, 

A more serious complication is that under both AmigaDOS 
1.3 and AmigaDOS 2.0 the script is actually launched using 
rx. The only difference is that in one case the rx is explicit. 
While being able to omit the rx command is cosmetically 
nicer, in both cases the default host for the process is not the 
underlying CLI (or Shell) but REXX. As proof, run the fol- 
lowing program; 

/** rexx:addresstest.rexx 

'•/ 

say "Hi, my address Is" 

sayaddressO * 
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using rx addresstest. Because REXX is the default host, you 
encounter some unexpected problems. For example, wliat 
happens if you run the program: 

/"rexximydir.rexx 

* 

"dir" 

by t3rping: 

rx mydlr 

The correct answer is nothing. In interpreting the program, 
ARexx recognizes the single command clause and passes it 
to the default host, which is REXX itself. The second time 
REXX gets the command without quotes, because it ate one 
level of quotes when it interpreted the string. REXX now at- 
tempts to resolve dir as an instruction, and so on. To avoid 
an infinite loop, it will no longer pass the command to itself, 
therefore failing to resolve the command. The result is that 
nothing happens. 

The situation is quite different if you nm the same program 
from a truly ARexx integrated shell, such as the WShell re- 
placement shell marketed by William Hawes, the creator of 
ARexx. WShell knows about ARexx. 
When you type something such as my- 
command, WShell automatically searches 
the rexx: directory for an ARexx program 
with the name mycommand.rexx or my- 
command. This makes launching ARexx 
programs as simple as launching ordinary 
executabtes. Second, if you run the pro- 
gram addresstest.rexx from a WShell, the 
output will be something like: 



'•I 

say addressO 

address command 'dir >rain:dirllst' 

say addressO 

or, equivalently: 

/" rexx:dlrtofile2.rexK 

* 

say addre3s( ) 
address command 
'dlr>ram:dlrllst' 
say addressO 

(Note that the command clause must be in quotes in these ex- 
amples or ARexx will attempt to interpret the line and break 

on the : and the >.) 

While it may appear that using the ADDRESS COM- 
MAND instruction to run system commands is only slightly 
more cumbersome than having a WShell as a default host, ap- 
pearances are deceiving. Things get more complex when you 
wish to launch a series of commands that must be executed 
sequentially. 



"A simple mechanism 

for telling an ARexx 

exec to execute a 



WSH 1 



which is different from what happens in 
an Amiga Shell. This occurs because each 
WShell has an ARexx port and can serve 
as the default host for an ARexx program 
launched from it. If you run the program 
mydir.rexx from a WShell, ARexx recog- 
nizes "dir" as a command clause, strips off the quotes and 
passes dir to the default host, WSH 1, which treats dir as if 
you entered it from the keyboard. This makes issuing system 
commands much more transparent. 

A simple mechanism for telling an ARexx exec to execute 
a string as a system command is the ADDRESS instruction. 
Use it to change the default host for dir to be AmigaDOS. You 
may place the ADDRESS COMMAND instruction either in 
front of the command clause to be executed by AmigaDOS 
or on a separate line. When ADDRESS COMMAND appears 
on the same line as the command clause, it changes the de- 
fault host to COMMAND for only that clause; when the in- 
struction appears on a separate line, then it changes the de- 
fault host to COMMAND for all subsequent command 
clauses. Both methods are illustrated below. Try running each 
example from a CLI (or Shell) to see what happens. If you 
have WShell, launch each of them with and without using rx. 
No matter how these programs are launched, the command 
dir >ram:dirlist executes correctly; only the results returned 
by the ADDRESS function differ. 

/" r»xx:dlrtofilel.rexx 



string as a system 
command is the 



ADDRESS instruction. 



SUBTLETIES WITH MULTIPLE 
COMMANDS 

Consider the problem of printing a 
file with an ARexx exec using a pro- 
gram that requires a stack size of 20000 
when your default stack is 4000. If you 
run it from a WShell, the following 
program will work: 

/*' rexx:texprlnt.rexx 

"/ 

arg fitename 

"stack 20000" 

"dvllj -o par: work:dvlflles/"ftlename",dvi" 

exlto 



In this case the command clauses are 
sequentially issued to the same host, say WSH_1. If, howev- 
er, you modify the program to: 

f" rexx:texprlnt2.rexx 

"/ 

arg filename 

address command 

"stack 20000" 

"dvil| -o par: work:dvifiles/"flleriame".dvi" 

exit 

it will break because the stack will be too small for dvilj. Tlie 
COMMAND keyword in the ADDRESS instruction tells 
ARexx to execute each command as an independent process. 
Thus, effectively, the command: 

stack 20OOO 

is executed in one Amiga shell, and the command: 

dvllj -c par: work:dvlfltes/"(llename".dvl 

is issued in another. This would appear to be a serious limi- 
tation to running ARexx without WShell, but fortunately 
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there is a simple solution. Create a single string of commands, 
concatenating individual coininands separated by the line- 
feed character "OA"x. As in: 

string = "command 1"||"0a"x||command 2[|"0a"x||. . . 
Now, send this one string to a shell using: 

address command string 

This trick is very useful for ARexx execs that cannot de- 
pend upon the existence of WShell. 

A more interesting problem is to open a CLI to show the 
output of the dviljp command as it runs, and then close the 
shell when finished. In this case, the previous approach needs 
a somewhat arcane modification, as shown below for OS 2.0: 

/" rexx:printlt.rexx 

a 

arg filename 

siring = "stack 20000 +"||'Oa'x 

string = strlngH"run dvllj -o par: "fllename".dvi +" 

string = string||'Oa'x||"endcli" 

runstring = "run > CDn:10/10/100/100/prlnting..^close "||string 

address command runstrjng 
exItO 



A + is needed after each command be- 
cause the Amiga DOS run >con:... con- 
struction redirects the output of the com- 
mand series to a CLI; thus, now the 
multiple string command belongs to run 
and AmigaDOS 2.0 rules apply. Without 
the + characters, the stack 2000 command 
would go to the newly opened CLI and 
everything else would go to the shell that 
launched the program. 



address AmlgaTeX 

redirect subsequent commands to the indicated message ports. 

Be sure to note that ARexx does not interpret the string that 
immediately follows the ADDRESS instruction. If the string is 
enclosed in quotes, ARexx uses it as is; otherwise ARexx auto- 
matically converts it to uppercase. Because ARexx conducts a 
case-sensitive search for public message ports, you must pro- 
vide quotes whenever needed or the search will fail. ARexx 
does interpret the expression that follows the port name. 

A common mistake with the ADDRESS instruction is to try 
something clever, such as: 

/' program-specific code here '/ 
myprogram = "Pro Vector" 
/' more code here */ 
address myprogram command 

This trick fails to accomplish the desired result because 
ARexx attempts to pass the command to a port called MY- 
PROGRAiM, instead of Pro Vector. The VALUE keyword tells 
ARexx to interpret the symbol or string that follows, before 
constructing a port name. Hence: 

address value myprogram 

causes all subsequent commands to be forwarded to the port 
ProVector. Given the way in which the ARexx par- 
ser works, however, the instruction: 



ADDRESS CHANGES 

ARexx-capable applications have one 
or more public message ports to which you can send ARexx. 
When ARexx programs are launched from ■within an appli- 
cation, the default host is customarily set to be one of these 
ports. If the program needs to interact with more than one ap- 
plication, then you must repeatedly change the default host. 
To do so, you use one of the ADDRESS instruction's four 
general forms: 

ADDRESS Istrlnglsymbol) expression 
ADDRESS {siringlsymbol) 
ADDRESS VALUE expression 
ADDRESS 

You are already familiar with a special case of the first two 

forms from the previous examples that used ADDRESS 
COMMAND, either by itself or on the same line as the com- 
mand clause. While ADDRESS can take either COMMAND 
or VALUE as a keyword, all other strings that immediately 
follow the ADDRESS instruction are interpreted as the name 
of a public message port. Thus: 

address TURB0TEXT7 
address 'TxEd Plusi 
address 'ProVector' 
address FASTHOST 



"The names of 

all ARexx ports 

should be all 

uppercase." 



ADDRESS VALUE expressions 

cannot be followed by a command clause 
on the same Une. After ADDRESS VAL- 
UE is used, the default host for the pro- 
gram is changed. To make restoring the 
original default host simple, ARexx 
keeps both the new host and the previ- 
ous host in memory. Using the AD- 
DRESS instruction by itself toggles be- 
tween these two values. Therefore; 



address command 

r program-speciiic code here */ 

n = 7 

myprogram = ■'TURBOTEXT"n 

address value myprogram 

/' more code tiere '/ 

address 

say address( ) 

produces the output 

COMMAND 

Actually, you can use a trick to accomplish the same thing 
as the VALUE keyword without changing the default host. 
Use the INTERPRET instruction. A construction such as: 

interpret address myprogram command 

will work just as well. 

The Amiga style guidelines recommend that the naimes of 
ARexx ports should be all uppercase, which makes a lot of 
sense. First, it avoids the need for quoting the string that fol- 
lows the ADDRESS instruction, which is a common source 
of problems with ARexx programs. Second, when you write 
complicated programs that launch string execs containing an 
ADDRESS instruction, every extra required quote hurts. 
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(Note: The fact that the true name of a public message port 

is all uppercase does not prevent you from enhancing read- 
ability by typing names in mixed case. ARexx automatically 
converts the name to uppercase before sending any mes- 
sages, unless forced not to.) 

Unfortunately, not all current applications conform to the 
style guide's recommendations. For this reason you must 
know the correct name of a message port to send it a message. 
Its name should be in the application's manual. K not, you can 
run the program and then type: 

n "say showllst('p')" 

to view a list of all pubhc message ports- 

FLEXIBLE QUOTING NEEDED 

A final class of quoting problems arises when you try to in- 
clude ARexx string programs inside command clauses. As an 
example, consider one of the earliest ARexx-capable Amiga 
applications, the editor TxEd Plus. TxEd Plus lets you add or 
delete menu items that are capable of launching ARexx ex- 
ecs. The syntax of the command used for this purpose is: 

MENU n K "Menu Text" ARexx_program 

where n is a menu number from to 5, K is a letter specify- 
ing the keyboard alternative for the menu 
item, the text that follows is what appears 
in the menu, and ARexx^program speci- 
fies the name of the program to be run. At 
first glance this is not a bad syntax, but 
problems arise because TxEd Plus requires 
that quotes be used for its quoting charac- 
ters. 

Suppose that you wish to run an ARexx 
exec to add new menu entries. In that case, 
to add an entry to menu 5, with keyboard 
alternative Z, which launches the exec 
CalcStuff/calc.rexx, you have to type: 



end. The example below will work: 



MENU 5 B '"Begin numt>ered points" 
""txedstuff/newllne""'" 



"'INSERT ""\pointbegm" 



"The notion 



of a string program 



IS unique 
to ARexx." 



While this sort of program looks considerably more myste- 
rious than the preceding one, it is not difficult to understand. 
Remember that ARexx first processes the line before handing 
it on. This means that the outermost quotes in each string dis- 
appear and, simultaneously, the double-double quotes are con- 
verted to single<iouble quotes before the line is passed to TxEd 
Plus. When TxEd Plus receives it the line looks like: 

MENU 5 B "Begin numbered points"'lNSERT "\polntbegin";"txedstuff/ 
newline"' 

Examine the file startup.txed for more examples. 
This sort of programming would be much simpler if a more 
flexible way of handling the quoting problem had been 
adopted by the host application. One way to increase flexi- 
bility would be for the host to allow additional quoting char- 
acters, as well as a way to handle program strings that con- 
tain more than one line, as indicated by the presence of 
semicolons. An example of a program that handles this sort 
of scripting in a more general manner is provided by the ter- 
minal program VLT. Another way to overcome this kind of 
difficulty is to include keywords for the 
host to parse on instead of using quotes. 
An example of this sort of approach is tak- 
en in the editor program called TurboText. 
Obviously, many strategies can be adopt- 
ed to handle the proliferation of quotes 
that appear when people try to stuff string 
programs into command clauses; the com- 
mon feature of all solutions is that the host 
application has to be more flexible in its 
quoting than ARexx. 



MENU 5 Z '"Launch Calc CalcStuff/calc.rexx" 

Why do you need two sets of quotes enclosing Launch 
Calc? ARexx will eat the first set of quotes when it processes 
the line, and TxEd Plus requires the string that follows to be 
enclosed in double quotes if it contains spaces. Even the or- 
der of the quotes used in this example is forced upon you; if 
you type '"Launch Calc'" you will not obtain the desired out- 
come. The program name must also be enclosed in quotes so 
that ARexx does not attempt to do a division before passing 
the result to TxEd Plus, Because the quotes are eaten by 
ARexx, TxEd Plus receives a valid program name to pass to 
REXX whenever the new menu item is selected. 

While this example is not too bad, consider what happens 
if you replace the name of an ARexx program with a string 
program. A string program is an ARexx invention that allows 
you to execute short ARexx execs directly by typing: 

rx "llnel ; Ilne2 ; ... " 

where the semicolons are REXX's end-of-line character. Either 

single or double quotes are acceptable as delimiters for a 
string program. String programs let you avoid having a large 
number of small ARexx files associated with an exec that cre- 
ates multiple menu entries. Because an enclosing set of quotes 
must survive after ARexx has eaten the outermost quotes in 
the example, you must use all of your tricks to achieve that 



FINAL ADVICE 

ARexx has abilities that transcend those 
possessed by REXX on any other platform. With these pow- 
ers, however, comes added complexity. Understanding how 
comnnand clauses get passed to a host apphcation is impera- 
tive. The ADDRESS instruction includes a mechanism for 
sending ARexx messages to public message ports, but you 
must remember that port names are case sensitive and that you 
need the VALUE keyword to use a computed string in the 
ADDRESS instruction. Finally, the notion of a string program 
is unique to ARexx. While this is a very powerful facility, ex- 
ploiting it can lead to bizarrely complicated quoting patterns. 
The key to working out these complexities is to keep in mind: 

• ARexx eats one level of quoting each time it processes a Une. 

• ARexx converts escaped quotes (double-double or double- 
single quotes) to ordinary quotes each time it processes a line. 

• You must also know how the host application handles the 
processed line when it receives it. 

If in a given project you find it difficult to sort out quoting 
complexity, then making liberal use of the tracing console and 
ARexx's built-in tracing commands can provide you with 
valuable insights into what is happening. ■ 

Marvin Weiustein uses ARexx and REKX extensively in his 
work at the Stanford Linear Accelerator, Write to him cjo The 
AmigaWorld Tech Journal, 80 Elm St., Peterborough, NH 
03458, or contact him on BIX (mweinstein). 
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This is the most cost effective way to 
increase the speed of your computer. 
AdSpeed™ I 




AdSpeed 

ICD expands its line of innovative enhancement products for the Amiga with the 
introduction of AdSpeed, a low cost, full featured 14.3 megahertz accelerator for 
all 68000-based Amiga computers. 

A.dSpeed differs from other accelerators by using an intelligent 16K static RAM 
cache to allow zero wait state execution of many operations at twice the regular 
speed. All programs will show improvement. No 68000 or 68020 accelerator 
without on board RAM will make an Amiga run faster. 

AdSpeed continues ICD's tradition of providing the best product available. 
These are .some of the features that set it apart from the rest: 

• Works with all 68000-based Amiga computers, including the 500, 1000, and 
2000. 

• Simple no solder installation — just remove the computer's 68000 and plug 
AdSpeed into its socket. 

• Low power, high speed CMOS 68000 CPU for full 100% instruction set com- 
patibility. 

• Software selectable speeds, with a true 7.16 megahertz mode for 100% com- 
patibility. Switches speeds on the fly without rebooting the computer. 

• 32 kilobytes of high speed static RAM — 1 6K of data/instruction cache and 
16K of cache tag memory. 

• Full read and write-through cache for greatest speed. 

• Bus monitoring to prevent DMA conflicts. 

• ICD's famous quality, dependability, and support. 

• Worlds smallest 68000 accelerator. (Photo above is actual size). 



ICD, Incorporated 1220 Rock Street Rockford, IL61101 USA 

(815) 968-2228 Information (800) 373-7700 Orders (815) 968-6888 FAX 

AdSpeed h a trademark of ICD, Inc. Amiga is □ regiiilercd rrodemark oif Comnx>do re- Amiga, Inc. 




DIGGING DEEP IN THE OS 



/\ Floating-Point 
\t Math Alternatives 



By John Fous! 



CHOOSING THE WRONG floating-point math model for 

your C program could cut performance in half, double or 
triple memory consumption, or introduce numeric error in 
calculations. It might even prevent your program from run- 
ning on some Amigas. Balancing these trade-offs and pick- 
ing the best model requires an understanding of AmigaDOS's 
floating-point math libraries, how a C compiler translates 
floating-point operations to assembly language, and how a 
compiler's link libraries perform math operations. 

First, take a look at what your choices are. Several of the 
system libraries contain functions that perform math opera- 
tions with IEEE (Institute of Electrical and Electronic Engi- 
neers) and FFP (Fast floating-point) floating-point numbers. 
Table 1 lists the system math libraries and the type of func- 
tions they contain. The base math libraries perform simple 
operations (addition, multiplication, negation, and so on), 
while the transcendental libraries contain functions such as 
sine and cosine, plus functions to translate numbers between 
IEEE and FFP formats. (For a complete list of math library 
functions see the Amiga ROM Kernel Reference Manual: In- 
cludes & Autodocs, Addison- Wesley.) 

The Motorola fast floating-point system stores floating- 
point numbers in 32 bits. The IEEE 754 standard includes 
both single-precision values in 32 bits and double-precision 
values in 64 bits. Motorola's 68881 and 68882 numeric co- 
processor chips use the IEEE format. Table 2 shows each rep- 
resentation's minimum and maximum values for numbers 
(using C's version of scientific notation), the digits of preci- 
sion (relevant number of digits after the decimal point), along 
with the storage size. 

The Motorola coprocessors and the Amiga OS double-pre- 
cision IEEE libraries use double-extended numbers for their 
intermediate calculations. These numbers use 80 bits of stor- 
age. Both SAS and Manx C store these types in 96 bits (12 
bytes) of data storage. Tliey could be stored in just ten bytes, 
but storing them in three 32-bit longs is faster and more con- 
venient, especially on the 68020. 

OLD STYLE OR STANDARD 

What's the difference between FFP and IEEE? FFP math is 
quite fast, even though the calculations are done in software. 
It does not offer double precision, however, or speed up if a 
coprocessor is available. The IEEE format offers both single 
and double precision for more freedom and control over 
floating-point calculation and storage. If your programs are 
going to exchange binary data with other types of comput- 
ers, IEEE is a good choice. Although, IEEE is about twice as 
slow as FFP, it will perform as fast or faster than FFP if a co- 
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processor is present. 

Your C compiler adds another level of complexity to your 
choice. In Standard C programs, there are three possible float- 
ing-point data types: float, double, and long double. Standard 
C allows a compiler to represent the float, double, and long 
double types in the same way. (It recommends a floating- 
point representation with a range similar to single-precision 
IEEE, meaning that the FFP model is not quite good enough 
for Standard C.) Having both floats and doubles represented 
by single-precision values is perfecfly legal under the FFP 
models and is supported in Manx and SAS C. Even under 
IEEE math models, SAS C has compiler switches to set the rep- 
resentation of float and double types. With these, you can rep- 
resent all floating-point types as either single- or double-pre- 
cision, or split-single and double types as different precisions. 

In an expression that combines floating-point variables 
with built-in operators such as +, -, *, and /, the compiler eval- 
uates the expression in a predictable way, to generate as- 
sembly language and data to represent the floating-point val- 
ues. In evaluating the expression, a conversion between types 
can take place: integers can be converted to floats, floats to 
doubles, and so on, before the rest of the expression is eval- 
uated. Promotion from one type to another is defined to 
progress from int to float to double to long double. For ex- 
ample, in an expression involving an int and a double (and 
no other type casts), the integers are promoted to doubles, 
and the entire expression is performed in double precision. 

When calling a function with floating-point arguments, 
similar promotion can take place. In old-style C, all floating- 
point arithmetic was defined to take place in double preci- 
sion. In a function call, all float parameters were promoted 
to double, then pushed on the stack. Under Standard C, a 
function's prototype determines if floats will be promoted to 
double before being pushed on the stack. In the absence of a 
function prototype, promotion takes place as in old-style C. 
If a Standard C function prototype says the argument is a 
float, it stays a float. 

Take a look at the theory in action. Listing 1 shows a very 
short C function that loads a constant into a double, multi- 
plies that double by two, then takes the cosine of it and stores 
it into a long double. In math.h, the cosO function is declared 
as accepting a double and returning a double. Listing 2 
shows the assembly language generated for this function, 
as compiled for FFP math and generated by the Manx 5.0 
compiler. Listing 3 shows the IEEE version. Listing 4 shows 
it under double-extended IEEE, and Listing 5 shows it with 
direct in-line 68881 codes. 

Examine these listings side by side and you will quickly see 



the difference in the code generated under each math mod- 
el. In the FFP listing, no distinction is made between float, 
double, and long double. Simple 32-bit values are loaded 
into registers, and such internal subroutines as jsr .fmul# are- 
called to perform math. In the IEEE and double-IEEE list 



Listing 1: Original (unclion() 

#lnclude <math.h> 
functlonO 

{ 
float a; 



double b; 
long double c; 

b = 3.14159; 

a = b • 2; 



Table 1 

Amiga library 


Contents 


mathffp.llbrary 


FFP math functions 


mathtrans.library 


FFP transcendental functions 


mathieeesingbas.llbrary 


IEEE math operator library, 
uses coprocessor if present 


mathleeesingtrans.llbrary 


IEEE transcendental library, 
uses coprocessor if present 


mathieeedoubbas.llbrary 


IEEE double precision library, 
uses coprocessor If present 


mathieeedoublrans.library 


IEEE double transcendentais, 
uses coprocessor if present 



Table 2 

Type 


Minimum 


Maximum 


Digits of 
Precision 


Size 
in bits 


FFP 


5.4e-20 


9.2e19 


6-7 


32 
32 


Single IEEE 


1.3e-38 


3.4e3S 


6-7 


Double IEEE 


2,2e-308 


1. 86307 


15-16 


64 


Double Extended IEEE 


3.4e4932 


1.2e4932 


19 


80(96) 



c s cos(a}; 



Listing 2: FFP 

; #include <math.h> 

I 

; functlonO 

;{ 

xdef _funetion 

Junction: 

link a5,#.2 

movem.l .3,-(sp) 

; floats; 

; double b; 

; long double c; 



;b = 3.14159; 



move.i #$c90fd042,-12(a5) 


; a = b ' 2; 


moveJ -12(85)40 


move.i #$80000042,di 


Jsr .Fmul# 


move.1 d0.-4(a5) 


;c = cos(a); 


cir.l -{sp) 


move.i -4(a5),-{sp) 


jsr _cos 


add.w #8,sp 


move.i dO,-20(a5) 



;} 

.4 

movem.l (sp)+,.3 

unik as 

rts 
.2 equ -20 
.3 feg 



xref _cos 
xref .begin 
(taeg 
end 



Listing 3: IEEE 

; #include <mstti.h> 

; functlonO 

:( 

xdef Junction 

Junction: 
link a5,#.2 
movem.l .3,-(sp) 

; float a; 

; double b; 

; long double c; 



; b = 3.14159; 

move.i #$f01b8eel,-8{a5) 

move.l j!»$400921f9,-12(a5) 



;asb*2; 

move.i -8(a5),d1 
move.i -I2(a5),d0 
move.) #$00000000,d3 
move.i #$40000000,d2 
Jsr .Pmui« 
Jsr .dtof# 
move.i d0,-4(a5) 
1 

; c = cos(a); 
move.i •4(aS),dO 
Jsr .ftod* 
move.i dl,-(sp) 
move.i dO,-(sp) 
Jsr _co3 



add.w ^,sp 
move.i dl,-l6(a5) 
move.l d0,-20{a5) 

;1 

.4 

movem.t (sp)+,.3 

unIk a5 

rts 

.2 equ -20 

.3 reg d2/d3 



xref _cos 
xref .begin 
dseg 
end 
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Listing 4: Double-Extended IEEE 
#{nclude <:math.h> 

tuncUonO 

{ 
xdef _func11on 
_tunction: 
link a5,#.2 
movem.i .3,-(sp) 

float a; 

double b; 

long double c; 



b = 3.14159; 

move.l #$f01b866f,-8(aS) 
move.1 #$400921 f9,-l2(a5) 



;a = b*2; 
move.) •8(a5),d1 
move.1 -12(a5),d0 
move.) #SOO00OOOO,d3 
move.! #$40000000,d2 
jsr .Pmultf 
jsr .dto1# 
move.l d0,-4(a5) 

; c = cos(a); 
move.l -4{a5),d0 
Jar .ftod# 
move.l d1,-(sp) 
move.l dO,-(sp) 
jsr _cos 
add.w #8,8p 
|sr .dtox# 



L inove.1 


.pO+3,-16<aS) 


move.l 


.pO+4,-20(a5) 


move. 


.pO,-24{aS) 


:} 




.4 




movem.i (sp)+,.3 


unik 


aS 


rts 




2 equ 


-24 


.3 regd2/d3 


xref 

i 


pO 


xref 


_C08 


xref 


begin 


dseg 




end 





Listing 5: Direct 68601 
^include <math.h> 

functlonO 

{ 
xdef Junction 
Junction: 
link a5,«.2 
movem.l .3,-{sp) 
fmovem.x .4,-(sp) 

floats; 

double b; 

long double c; 



; b = 3.14159; 




.5 


move.l «$f01b866f,-8(a5) 




fmovem.x (sp)+,.4 


move.l #$400921 f9,-l2(aS) 




movem.l (sp)+,.3 
unIk as 


; a = b * 2; 




rts 


Iinove.d-12(a5),fp0 




.2 equ -24 


fmul.d #"$4000000000000000 


■,fp0 


.3 reg 


fmove.s fp0,-4{a5) 




.4 freg 


; c = cos(a); 






fmove.s •4(a5),fp0 




xref .begin 


fcos.x fpO 




dseg 


fmove.x fp0,-24(a5) 




end 


;) 







ings, the double constants are twice as large as the FFP con- 
stants. Storing doubles in memory or on disk consumes twice 
the memory or disk space as using single precision. In the c= 
cos(a) line of the double-IEEE listing, note that it takes three 
long-word move.l instructions to store the long-double quan- 
tity. The direct 68881 listing is very different than the others. 
In it the compiler generates special 68881 coprocessor in- 
structions (such as fmul.d and fcos.x fpO) instead of calling 
internal subroutines to perform the math. The limitation is 
you need a 68020 or 68030 CPU, plus a coprocessor chip to 
run the program. 

COPROCESSOR COOPERATION 

The 68020 and 68030 support direct, tight-coupled access 
to the numeric coprocessor chip. The 68000 supports only a 
slower interface, treating the 68881 coprocessor as a periph- 
eral device. At one time Microbotics and CMI provided a re- 
placement ma thieeedoubbas. library that called their periph- 
eral 68881s, allowing 68000-based Amigas to use the 68881 as 
a peripheral. Although these devices could double the speed 
of math operations, they never became commonplace. Un- 
fortunately, few commercial applications used the IEEE dou- 
ble-precision library. As the Amiga market matured, math- 
intensive programs were usually offered in two forms: an 
integer- or FFP-based version that worked quickly on any 
Amiga and a version compiled for the Amigas equipped with 



a 68020 and 68882. Since Amiga OS 1.3, however, the double- 
precision libraries can take advantage of numeric coproces- 
sor chips, as long as they declare a math resource during the 
autoconfig process. This means both 68000/68881 and 
68020/68882 combinations give faster results, if present. 

In Amiga OS 2.0, Commodore added a new math- 
ieeesingbas. library that has the same functions as the 
matliffp.library, except that it uses a math resource if present. 
This library gives the speed of single-precision IEEE with the 
added benefit of using a coprocessor, if present. Under Ami- 
ga OS 2.0, the system will not auto-init the library, so it is not 
on the library list until an application asks for it. Under very 
low memory the library init could fail, therefore do not as- 
sume success. Check the result of the OpenLibraryO call be- 
fore continuing. 

LIBRARY LINGO 

After the compiler turns the assembly language interme- 
diate file to an object file, the linker comes into play. Do not 
be confused by the word "library." It has two contexts in a 
math models discussion: A given compiler has link libraries, 
and the Amiga OS has math libraries. An OS library is es- 
sentially a program that contains useful subroutines that any 
other program can call — the mathteeedoubbas.library in the 
LIBS: directory is an example. A compiler's link libraries are 
composed of object .o modules that contain definitions of • 
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RXTools 



RXTools is an object oriented interface builder which extends the capabilities 
of ARexx and the Amiga. With the built in editor, RXTools provides a complete 
development system for ARexx on the Amiga. 



ARexx function host environment system which runs in the background - ARexx Required. 
Allows you to create windows, gadgets, requesters and more within your ARexx applications. 
Provides a programming addition to ARexx not otherwise available. 
Built in editor allows easy manipulation of RXTools and ARexx scripts. 
AmigaDOS VI. 3 and 2.0 Compatible. 
Retail Price $54.95 




MRBackup 
Professional 
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MRBackup Professional allows for easy yet powerful backup 
commands at the click of a gadget. MRBackup Professional will allow 
backups to floppy, another hard drive, virtual file, SCSI streaming tape, or even to DAT tape. 
• SCSI Streaming Tape Capability - Use your existing controUer and a SCSI tape drive, NO Extra hardware 
required (most controllers and SCSI drives supported). • Utilizes full compression. (12 to 16 bit), to save 
backup space. - With FastDisk option, even floppy backups take less time. • Has full ARexx integration. - 
Allows for complete external control of the backup options." AmigaDOS VI. 3 V2.0 Compatible. 

Retail Price $54.95. With Tanberg 150Mb SCSI Streaming Tape External $949.95 Internal $749.95. 
Wangtek 150Mb SCSI Streaming Tape External $999.95 Internal 799.95, 

Sony ftill height DAT External $2049.95 Internal $1849.95. 
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Sapphire Accelerator 

68020 / 68881 




Fits snugly In an Amiga 1000, 500, and 2000 

For easy installation, included is a disk with instnactions, pictures and some public 
domain benchmark software. Also included is an electrostatic discharge (ESD) 
information card, and an ESD safety strap. Features include: 

• Factory Installed 12 MHz 68020 CPU And 68881 FPU 32 Bit Processors operating at 7.16 MHz. 

• Speed Increases Of Up To 2.4 Times Faster In Integer, And 3.2 Times Faster 
In Floating Point. 

• SraaU Compact Size, Smallest Yet At Only 3 1/8" x 4 1/4" x 1/2". 

• Not A Pseudo Accelerator, but a true 32 Bit Accelerator Card 
Using 32 Bit Processors. 

• One Full Year Factory Warranty, 

• Retail Price 399.95 



TTR Development, Inc 

6701 Seybold Rd. Suite 220 
Madison, WI 53719 




Dealer Pricing Available! 



Sales And Technical Support 

608-277-8071 
BBS Support 608-277-8072 
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INNOVATIVE SOFTWARE FOR 
THE COMPUTER INSIDE US ALL 



Bix support under TTR. Support 
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such C library functions as fopenO. Other link libraries — 
one for each math model — contain subroutines that perform 
arithmetic operations on floating-point numbers. When you 
link your program's object modules, the final executable is a 
mixture of the functions that you wrote plus functions from 
the standard link libraries. If your program performs float- 
ing-point math, you must link with the proper library to per- 
form those math operations. 

To complicate things, a compiler's math link library can in- 
voke functions in an OS library. An example is SAS C's 
icmieee.lib link library. It opens the Amiga's IEEE library to 
perform math. (Also, note that both IVlanx and SAS C offer 
IEEE link libraries that do not open the system's libraries, but 
instead link in a stand-alone IEEE math implementation.) 

By linking with the proper math link library, internal sub- 
routines such as the jsr .fmul# are resolved. Listing 6 shows 
the source code for the interna! subroutine .Fmul. It simply 
calls the SPMuK ) function in the Amiga's ITP library, inside 
the amiga_ffp# internal subroutine, which first checks to 
make sure that library is open and ready. 



Listing 6: Direct 68881 

; Copyright (C) 1986 by Manx Software Systems, Inc. 
;:t9s8 

public .Fmul] 

.Fmul: 
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move.! #_LVOSPMul#,-(sp) 
]mp amlga_fi|>tf 

One common mistake is to list the link libraries in the 
wTong order when telling the linker how to produce an exe- 
cutable. The symptom is that floating-point numbers do not 
print from the printfO hinction. For example, in Manx C's 
IEEE model, you need to specify the ma.lib before the c.lib. 
Each math Hnk library contains a variant of the printfO func- 
tion that understands the math model. Be careful, the Stan- 
dard C link library has a version of printf( ) that does not un- 
derstand the %f format specifier. If the linker sees the c.lib 
printfO before the math library printfO, it links the wrong 
function into your executable. 

THE CHOICE IS YOURS 

This might seem obvious, but if your program does not 
perform any floating-point operations, then you do not need 
to link it with a math library. What defines a math operation? 
Any part of an expression involving a floating-point type, or 
a cast to a floating-point type, invokes internal math func- 
tions. For example, even though a program has no floating- 
point variables, an expression in the program might cast in- 
teger variables to floats to perform an accurate division by a 
fractional number. 

As you can see in the assembly language listings, it is pos- 
sible to initialize floating-point variables without linking with 
a math library, as long as you do not use any Standard C op 
erators with these variables. If you open a math library on 
your own and call the SPMulO function yourself, there is no 
overhead of jumping through the compiler's stubs and in- 
ternal subroutines. 

If }'ou want raw speed, consider integer math. If your ap- 
plication can avoid floating-point and perform fixed-point in- 
teger arithmetic, chances are it will be faster than any float- 
ing-point implementation. 

If you do need to use a Hbrary, the FFP libraries are about 
twice as fast as 1.3 IEEE libraries and give a reasonable 
amount of precision for most applications. OS 2.0's math- 
ieeesingbas.library, however, complicates your choice. One of 
the main advantages of the FFP library was that it was in 
ROM and thus available on every Amiga. Because the library 
was also relatively fast for nonhardware-assisted math, it 
was the correct choice. With the arrival of high-end applica- 
tons that need more accuracy and speed coupled with in- 
dustry pressure for a standard floating-point format, CATS 
staffers recommend the mathieeesingbas.library which is 
built in ROM, almost as fast as the mathffp.Iibrary on non- 
coprocessor machines, and much faster on coprocessor- 
equipped Amigas. 

If you prefer accuracy, standardization, and the added bene- 
fit of running much faster on enhanced machines, choose the 
IEEE libraries or consider direct 68881 instructions for the 
fastest possible math on enhanced Amigas. Also, tliere is no rea- 
son not to turn on your compiler's 68020 code generation, be- 
cause all 68881 -equipped Amigas ha ve an advanced processor. 

As with al! program design choices, the "best" math mod- 
el involves decisions about speed and storage. Keep your 
preferences and the above tips in mind, and the trade-offs be- 
tween math models will be more apparent. ■ 

John Foust is president of Syndesis Corp. Contact him c/o The 
Amiga World Tech Journal, 80 Elm St., Peterborough, NH 03458. 
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\^ The GadTools Library 



By Paul Mifter 



WORKBENCH 2.0'S PROFESSIONAL look and opera- 
tional consistency are attributable primarily to the new gad- 
get constructs available in the GadTools library. An integral 
part of this latest operating system, GadTools combines the 
look of 2.0 and aspects of several standard controls to form a 
set of new gadget classes. These gadgets can make your life 
much easier, and that's why GadTools is not just a tool — it is 
an interface programmer's friend! 

The best thing about GadTools is its ease of use. GadTools 
lets you create an entire list of complicated gadgets with 
much less effort and hassle than you are used to. With one 
function and a few parameters, for example, you can create 
an entire scrollable list gadget, complete with slider and ar- 
row buttons — GadTools automatically combines the neces- 
sary controls into a single gadget. No longer must you cre- 
ate a proportional gadget and combine it with two Boolean 
gadgets to make a scroller — simply ask for a Scroller Gad- 
Tools gadget, and the system takes care of the busy work and 
maintenance for you! 

GadTools is also extremely extensible. This means that as 
new gadget classes and parameters become available, you 
can easily add them using 2.0's tag facility. Tags are a means 
of providing information to many nevv 2.0 functions without 
filling out such large temporary structures as NewScreen and 
NewWindow. They also allow the easy addition of new fea- 
tures. If you omit tags, the system typically defaults to a 
group of standard settings. For that reason, you need set only 
the specific parameters you require. 

Tags are specified either as an array of Tagltems or as vari- 
able parameters — containing the tag and its data — to the 
function. Here is the format of the Tagltem structure: 

typedel ULONG Tag; 

struct Tagllem { 

Tag tl_Tag; /' lag ID '/ 
ULONG ti_Data; 

I; 

Tagltem lists are terminated with a tag of type TAG_DONE 
or TAG_END. 

TAG— YOU'RE A GADGET! 

In version 36 of gadtools.librar)', there are 13 kinds of gad- 
gets. Each type has a set of tags that specify required or spe- 
cial information about the gadget. 

Both the GENER1C_K1ND (a standard gadget type) and 
BUTTON_KIND (an action button) accept the disable tag. 
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This also applies to most other gadget types: 

QA_DISABLED (BOOL; delault = FALSE) 

Set to TRUE lo disable ttie gadget, FALSE otherwise. 

The CHECKBOX_KIND is a state-selecting gadget. A 
checkmark appears when the gadget is activated. You can use 

the check tag with it: 

GTCB_Checked (BOOL; delauH = FALSE) 

The Initial state of the checkbox {TRUE = CHECKED). 

The CYCLE^KIND is a single button with multiple states. 
This gadget q'cles forward through a list of strings each time 
you click on it. It also cycles backward through the list when you 
hold down the Shift key and click. Its corresponding tags are: 

GTC¥_Labels (STRPTR •) 

A required tag, this Is a NULL-termlnated array of string pointers. 

These strings comprise the gadget's offerings. 
GTC¥_Active (UWORD; delault = 0) 

The ordinal number (counting from zero) of the initially active 

choice in the cycle. 

INTEGER_KIND is a standard string-editing gadget that 
allows you to edit only integers. The Integer gadget accepts 
these tags; 

GTIN„Number (ULONG; default = 0) 

Determines the initial contents of the integer gadget. 
GTIN_MaxChars (UWORD; default = 10) 

The maximum number of digits that the Integer gadget can hold. 

A powerful gadget, LISTVIEW KIND displays a list of 
items that you can select and scroll through. It has an optional 
scroll bar with arrows and an optional editing facility for the 
selected item. ListView accepts several tags: 

GTLV_Top (UWORD; default = 0) 

Determines the top item (ordinal) visible In the llsl. 

GTLV Labels (struct List •) 

A required tag, this acts as a pointer to an Exec List of lat>els 
whose ln_Mame fields are displayed In the list. 

GTLV Readonly (BOOL; default = FALSE) 
If TRUE, LIstVlew is a read-only gadget. 

GTLV_ScroliWidlh (UWORD; default = 16) 
Determines the width of the scroll bar. 

GTLV ShowSelected (struct gadget *) 

Set to NULL to have the currently selected item displayed be- 
neath the list. Alternately, set to a pointer to an existing GadTools 
STRING_KIND gadget If you wrant an editable display of the 
currently selected item. 



'GadTools lets you create an entire list of complicated gadgets with 
much less effort and hassle than you are used to." 



GTLVSelected (UWORD; default = -0) 

Ordinal number of the currently selected Item, or -0 (or no cur- 
rent selection. 

LA¥OUTA_SPACING (default = 0) 

Extra space to place between lines of the list. 

The MX KIND gadget provides a set of items that, like ra- 
dio controls, you can select only one at a time. Its tags are: 

GTMX_Labels (STRPTR ") 

This tag is required. It serves as a l4ULL-termlnated array of 
string pointers. These strings will appear as the latiels beside the 
choices In the gadget. 

GTMX_Actlve (UWORD; default = 0) 

The ordinal number (counting from zero) of the initially active 
choice in the gadget. 

GTMX_Spaclng (UWORD; default = 1) 

The amount of space between each choice of a set of mutually 
exclusive gadgets. This amount, added to the font height, pro- 
duces the vertical shift between choices. 

NUMBER_KIND is a read-only display gadget for inte- 
gers. To it you can add: 

GTNM_Number (default = 0) 

A signed long Integer to be displayed as a read-only number. 
GTNM_Border (BOOL; default = FALSE) 

II TRUE, this flag causes a recessed border to appear around the 

gadget. 

The PALETTE_KIND gadget contains a display of all the 

available colors for the current screen, in addition to a box 
containing the "current" color — that is, the color selected 
from the gadget. The Palette gadget tags include: 

GTPA_Depth (UWORD; default = 1) 

Sets the number of bitplanes In the palette. 
GTPAColor (UBYTE; default = 1 ) 

The palette color selected Initially. 
GTPA_ColorOffset (UBYTE; default = 0) 

Determines which color to use first In the palette. 
GTPA JndlcatorWIdth (UWORD) 

Determines the width of the current-color Indicator. Set this If you 

want the indicator to appear above the palette. 
GTPAJndicatorHeight (UWORD) 

Determines the height of the current-color Indicator. Use this tag 

If you want to place the Indicator to the left of the palette. 

The SCROLLER_KIND gadget combines a proportional 



slider and two optional arrow buttons. The result is a 
ready-to-go scroller gadget that automatically tracks the 
position and size of the slider control. You have your 
choice of several tags for the Scroller gadget: 

GTSC_Top (WORD; default = 0) 

Determines what appears at the top of the area that the scroller 

represents. 
GTSC_Total (WORD; default = 0) 

The total number of items In the scroller area, 
GTSC_Vlslble (WORD; default = 2) 

The numtier of things visible in the scroller. 
GTSC_Arrows (UWORD) 

Attaches arrows to the scroller. The value supplied serves as the 

width of each arrow button for a horizontal scroller or the height 

of each button for a vertical scroller (the other dimension match- 
es the whole scroller). 
PGA_FREEDOM (default = LORIENT_HOHIZ) 

Determines whether the scroller Is horizontal or vertical. Choose 

from LORIENT VERTor LORIENT HORIZ. 
GAJMMEDIATE (BOOL; default = FALSE) 

Set to TRUE if you want to be notified of every GADGETDOWN 

event from the scroller. 
GA_RELVERIFY (BOOL; default = FALSE) 

Set to TRUE if you want to be notified of every QADQETUP event 

from the scroller. 

The SL1DER_KIND combines a proportional gadget and, 
optionally, a numeric display that depicts the level or inten- 
sity of some value. Corresponding tags are: 

GTSL_Min (WORD; default = 0) 

Sets the minimum level of the slider. 
GTSL_Max (WORD; default = 15) 

Maximum level of the slider. 
GTSL_Level (WORD; default = 0) 

Current level of the slider. 
GTSL_Maj<LevelLen (UWORD) 

Maximum length In characters of the level string when rendered 

beside the slider. 
GTSL^LevelFormat (STRPTR) 

A C-style formatting string for the slider level. Be sure to use the I 

(long) modifier. This string Is processed using the EXEC RawDo- 

Fmt() function. 
GTSL LevelPlace (default = PLACETEXT_LEFT) 

Indicates where the level Indicator appears relative to the slider. 

Settings are PLACETEXT_LEFT, PLACETEXT^RIGHT, PLACE- 

TEXT_ABOVE, or PLACETEXT_BELOW. ■ 
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GTSL_DlspFuiic ([LONGffuncHon)(struct gadget ', WORD)]; 

default = 0) 

This function calculates the level to be displayed. For example, a 
slider to select the number of colors might require a (1 « n) 
function here. Your function must take a pointer to a gadget as 
the first parameter, the level (a WORD) as the second, and return 
the result as a LONG. 

GA_IMMEDIATE (BOOL; default = FALSE) 

Set to TRUE if you want to be notified of each slider GADGET- 
DOWN event. 

GA_RELVERIF¥ (BOOL; default = FALSE) 

Set to TRUE If you want to be notified of each slider QADGETUP 
event. 

PGA_FREEDOM (default = LORIENT_HORIZ) 

Set to LORIEMT_VEHT or LORIENT_HORIZ to create a vertical or 
horizontal slider. 

STR1NG_KIND is a standard alphanumeric string-editing 

gadget. The tags it supports are: 

GTST string (STRPTR; default = NULL) 

Specifies the initial contents of the string gadget. Set It to NULL if 

the beginning of the string Is to be empty. 
GTST MaxChars (UWORD) 

The maximum numt>er of characters that the string gadget Is to hold. 

TEXT_KIND, the last type of gadget, is a read-only al- 
phanumeric text display. For tags you can choose among: 

GTTX_Te)rt (default = NULL) 

Serves as a pointer to a NULL terminated string to be displayed 

as a read-only text-display gadget or NULL. 
GTTX_CopyText (BOOL; default = FALSE) 

This flag Instructs the text-display gadget to copy the supplied 

text string Instead of continuing to refer to the address of the 

supplied string. 
GTTX_Border (BOOL; default = FALSE) 

If TRUE, this flag causes a recessed border to surround the gadget. 

SET UP AND AWAY 

Because GadTools resides in a ROM Ubrary, you must do 
some initial setting up before you can actually create a gad- 
get. GadTools also requires a pointer to a Visual Info block, 
which you can get by accessing either the Workbench screen 
or a custom screen. Finally, because Workbench 2.0 allows the 
user to choose almost any font as the standard, GadTools is 
very font-size specific and thus must know your font choice 
so it can place gadget text properly. You will typically want 
to force Topaz 80, so ask for it explicitly. See the setupO func- 
tion in the demo program (in the Miller dravver of the ac- 
companying disk) for the initialization described here. 

Now you are ready to create a gadget list. Because all Gad- 
Tools gadgets are dynamically allocated, GadTools provides 
a simple way for linking, adding, refreshing, and freeing en- 
tire lists of gadgets. To define your gadget list, declare a point- 
er to a gadget structure and call the GadTools CreateCon- 
textO function with the pointer's address: 

struct gadget 'glist = NULL; 

struct gadget 'gad; 

gad = CreateContext(&gli5t); 

This allocates a private gadget that describes the list. It also 
forms a base to which you can add more gadgets, and on 



which you can perform gadget-adding and -refreshing opera- 
tions. Use the returned gadget pointer as a foundation for 
building your gadget list with CreateGadgetO. 

CreateGadgetO is the variable-arguments version of the 
gadget-allocation function and takes the gadget type, a point- 
er to the previous gadget, a pointer to a NewGadget struc- 
ture, and the GadTools gadget tags as its parameters. The 
physical description of the gadget is specified in the New- 
Gadget structure: 

stioicl NewGadget 

( 

WORD ng_LeftEdge, ngTopEdge; r upper-teft '/ 
WORD ng_^Width, ng_Height; /* size "/ 
UBYTE •ng_GadgetTeKt; r text label */ 
struct TextAttr •ng_TextAttr; /* label font V 
UWORD ng_GadgetlD; /' gadget ID '/ 
ULONG ng Flags; /* special flags */ 
APTR ng_Vlsuallnto; r Visuallnio */ 
APTR ngUserData; T your data"/ 

1; 

Now, you must assign the Visuallnfo pointer (obtained 
earher) to the ng_VisuaIInfo field, and assign a declared Text- 
Attr structure to the ng_TextAttr field. Then, finally, you are 
ready to create a gadget. 

Fill out a NewGadget structure with the position and size 
of the gadget, a title, and an ID, along with the Font and 
Visuallnfo information. To create a simple gadget of type 
BUTTON_KIND, you simply pass the required informa- 
tion: 

gad = CreateGadget(BUTTON_KIN0, gad, &newgad, TAG_DONE); 

For a more complex type, say a Scroller gadget, you might 
want to add some more tags: 

gad = CreateGadget(SCROLLER„KIND, gad, &newgad, 
PGA_FREEDOM, LORIENT_VERT, 
GTSC„Tota!, 20, 
GTSC_Vlsibie, 10, 
GTSC_Arrows, 16, 
GA_RELVERIFY, TRUE, 
TAG^DONE); 

To allocate a complete list of gadgets, begin with the gad- 
get pointer returned from your CreateContextO call. Make 
the necessary adjustments to your NewGadget structure be- 
tween calls to CreateGadgetO, and then pass the gadget 
pointer returned from each call as the previous pointer in the 
following call. You need not check for allocation problems 
until the last gadget is requested, because CreateGadgetO 
will simply return a NULL pointer if it receives NULL as the 
previous gadget pointer. 

Once you have your gadget list, you can add it to a win- 
dow and refresh the imagery with the standard Intuition gad- 
get functions. Then you must call GT RefreshWindow( ) on 
the window, so special GadTools imagery can receive the 
proper treatment. Additionally, new GT_BeginRefresh() and 
GT_EndRefresh() functions are provided to replace the stan- 
dard Intuition window-refreshing functions. 

FURTHER EVENTS 

GadTools can also make dealing vnth gadget events much 
simpler. Using the new GT_GetIMsg() and GT_ReplyIMsgO 

Continued on p. 61 
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Inside SCSI 



Your system probably uses this interface every day, 
but do you know how it works? 



By Greg Berlin 



AS MORE COMPLEX tasks are required of microcom- 
puters, system designers face the challenge of integrating 
all the functions required of sometimes dissimilar compo- 
nents, while maximizing system performance and mini- 
mizing the cost and effort involved in putting the system 
together. The current method of choice is the Small Com- 
puter Systems Interface (SCSI, pronouned scuzzy). The 
SCSI bus provides a standard means of connecting multi- 
ple intelligent peripherals to a host computer (see Figure 1). 
Thus, you can add many different types of devices (large 
hard drives, tape drives, CD-ROMs, and so on) to the host 
computer without modifying the generic system hardware 
or software. 

While almost everyone has heard of SCSI, even many vet- 
eran computer users may not fully understand what SCSI is 
all about. First of all, the term small in SCSI's name imphes 
that its application is confined to microcomputers and that its 
performance is limited. (Tlie pronunciation "scuzzy" has not 
enhanced the standard's image, either.) As you will see, de- 
spite these misnomers, SCSI is indeed a powerful interface 
and well worth investigating thoroughly. It has found appli- 



cations in machines spanning the entire spectrum of perfor- 
mance and price. 

SCSI CONCEPTS 

A very basic, yet important point to understand is that the 
SCSI bus is an I/O (input/output) bus, as opposed to a sys- 
tem bus or a device-level interface bus. A system bus (such 
as ZORRO II /HI, NuBus, STD BUS, IBM PC BUS, or MULTI- 
BUS I/II) is generally the place to add expansion cards. De- 
vice-level interface buses (including ST-506, ESDI, SMD, and 
QIC-36) provide the means to take physical control of a de- 
vice, via analog or digital signals, to manage such tasks as 
head positioning and reading and writing raw data, Device- 
level interfaces can be attached directly to the system bus. A 
good example is the common ST-506/412 controller that 
plugs into the IBM PC BUS. Usually up to two ST506/412- 
compatible disk drives can be plugged into this controller 
board. While this method minimizes immediate cost, it lim- 
its expandability and versatility. If you want to add a tape 
drive, for instance, you need to purchase another device-in- 
terface controller card to support the tape-drive interface • 



SCSI History 



The SCSI interface's roots go back 
as far as the early 1960s. IBM's popu- 
lar mainframes at that time made 
use of a byte-wide parallel I/O bus, 
known as the block multiplexer chan- 
nel, that was capable of block trans- 
fers. Recognizing the need for an in- 
terface standard, the ANSI X3T9.3 
committee began to define one in the 
early 1980s. Despite the popularity of 
IBM's block multiplexer channel, the 
ANSI committee decided not to ac- 
cept it unchanged, due perhaps to the 
NIH (not invented here) syndrome or 
to political pressures from IBM's 
competitors. The standard that ANSI 
was developing was called the intel- 
ligent peripheral interface (IPI). The 
IPI bus was basically functionally 



equivalent to the block multiplexer 
channel, with a number of additions. 

As an alternative to the block mul- 
tiplexer channel of IBM, other groups 
were working on developing their 
own parallel I/O bus. Shugart Asso- 
ciates developed the Shugart Associ- 
ates System Interface (SASI). Shugart 
was in the business of manufacturing 
disk drives, and several other drive 
manufacturers followed the compa- 
ny's lead and adapted the SASI inter- 
face to their drives. Because several 
of the key drive manufacturers adopt- 
ed this interface, it became relatively 
widespread. 

Shugart obviously had a great in- 
terest in seeing their parallel interface 
bus, instead of the IPI bus, adopted by 
the ANSI X3T9.3 committee. When it 
appeared that SASI would lose the 



battle, Shugart renamed its bus inter- 
face "SCSI" and submitted it to the 
ANSI X3T9.2 committee, where the 
competition was less entrenched. 
(The ANSI X3T9.2 committee deals 
with low-level interfaces.) 

In 1984 the ANSI committee com- 
pleted the SCSI-1 specification, and it 
was published in its final form in 1986. 
Further improvements and refine- 
ments in the standard have resulted in 
the recent release of the SCSI-2 speci- 
fication, which is currently in its final 
draft review (and may be published 
by the time you read this). For a copy 
of the SCSI-2 draft proposal (docu- 
ment X3.1 31 -1 98X), contact Global En- 
gineering Documents, 2805 McGaw, 
Irvine, CA 92714, 800/854-7179. 

—GB 
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Figure 1: A Multiple-Host and Multiple-Peripheral SCSI System 
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(such as QlC-36). Systems that require several disks or other 
peripherals can benefit from the added SCSI bus I/O layer, 
SCSI offers advantages in flexibility and system performance. 
You can connect several different peripherals to a single SCSI 
I/O bus, and the peripherals can communicate directly with 
each other. Bus speed is certainly not a limiting factor, as 
SCSI transfer rates have now reached up to 40 megabytes 
per second (MB/sec). 

The SCSI bus can support up to eight devices connected to 
it. At first glance this may seem rather limiting, but the al- 
lowance in the spec for eight logical units per device and 256 
logical subunits per logical unit provides more than enough 
expansion. 

Each of the devices on the SCSI bus must be assigned a 
unique ID number, which is usually set with jumpers on the 
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device. The SCSI ID serves two purposes: It uniquely identi- 
fies a device on the bus and it defines the device's priority 
during bus arbitration (the higher the device number the 
higher its priority). 

Each of the eight possible devices is defined as an initiator, 
a target, or both. An initiator is part of the SCSI host adapter 
that connects a host computer system to the SCSI bus. In a 
typical system, a single initiator connects with one or more 
targets. A more complex system may have more than one 
SCSI host adapter (multiple initiators). Tliis type of system 
can not only establish communication from any processor to 
any peripheral, but also from a host to host, because the host 
adapter is itself a SCSI device and can be a target as well as 
an initiator. Two peripherals (targets), however, cannot nor- 
mally communicate with each other, and only two devices 
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(one initiator and one target) can communicate with each 
other over the bus at any one time. 

A host adapter consists of the hardware and software re- 
quired to connect to the SCSI bus as an initiator, as well as 
the hardware and software to interface this logic to the liost 
CPU. With the proliferation of single-chip SCSI controllers 
that can operate as both initiators and targets, constructing a 
SCSI host adapter has become quite easy. Typically, these 
single-chip devices attach directly to the SCSI bus on one 
side and, with a minimum of logic, are adaptable to any sys- 
tem bus on the other side, The SCSl-chip-to-system-bus in- 
terface can be as simple as software-polled I/O or more com- 
plex to enable high-speed data transfer via DMA. These 
single-chip controllers accept high-level commands and re- 
lieve the host CPU of the burden of manipulating and mon- 
itoring the SCSI bus signals. 

Host system software is simplified because it no longer 
has to be concerned with the physical attributes of the device. 
The SCSI interface uses logical rather than physical address- 
ing for all data blocks. 

SCSI BUS PHASES 

The SCSI protocol uses eight distinct logical phases: BUS 
FREE, ARBITRATION, SELECTION, RESELECTION, COM- 
MAND, DATA, STATUS, and MESSAGE. The last four are 
collectively known as the information transfer phases. The 
SCSI bus can be in only one of the eight states at a time. 

The BUS FREE phase signifies that no SCSI device is ac- 
tively using the SCSI bus, and that the bus is available for use. 
This phase is entered after a system reset or after the RST sig- 
nal resets the bus. The BUS FREE phase is indicated by the 
deassertion of the BSY and SEL signals. 

The ARBITRATION phase is entered when a SCSI device 
wishes to gain control of the bus as a master, This occurs 
when an initiator wants to select a target or a target wants to 
reselect its initiator. The ARBITRATION phase can be en- 
tered only from the BUS FREE phase. After a device deter- 
mines that the bus is free, ARBITRATION begins by assert- 
ing the BSY signal and the SCSI ID of the device making the 
request on the appropriate data bit. Each of the eight possi- 
ble SCSI devices uses a single data hne to indicate its pres- 
ence. The device with the highest ID number wins the arbi- 
tration and gains control of the bus (data bit 7 has the highest 
priority and bit the lowest). 

The SELECTION phase allows an initiator to select a tar- 
get for the purpose of initiating a target function, such as a 
READ or WRITE command. In SCSI-2 the SELECTION phase 
is always entered following an ARBITRATION phase. SCSI- 
I supported a single initiator option that eliminated the need 



for bus arbitration, so SELECTION could be entered follow- 
ing a BUS FREE phase. In both cases, the target is selected 
when the initiator puts the ID number of the target on the 
data lines and asserts the SEL signal. 

The optional RESELECTION phase occurs when a target 
device wants to reconnect with the initiator that previously 
sent it a command. This phase takes place basically the same 
as the SELECTION phase, except the I/O line is asserted 
along with the SEL signal so that it can be distinguished. 

The COMMAND, DATA, STATUS, and MESSAGE phas- 
es are grouped together as information-transfer phases be- 
cause they are all used to transfer data or control information 
via the data bus. The C/D, I/O, and MSG signals are used to 
distinguish between the different information transfer phas- 
es (see Figure 2). The target drives these signals and therefore 
controls all changes from one phase to another. The REQ/ 
ACK (and REQB/ ACKB) lines are used to control the trans- 
fer of data between the target and initiator during the infor- 
mation-transfer phases. 

The actual data transfer can be accomplished via syn- 
chronous or asynchronous protocols. Both methods make 
use of the ACK and REQ signal lines to perform the hand- 
shaking. The synchronous transfer mode is optional for a tar- 
get device. An initiator can request that a target perform syn- 
chronous transfer, but if it is rejected then asynchronous 
mode is used. 

When data is to be transferred to the initiator in asyn- 
chronous mode, the target drives the data Hnes and asserts 
the REQ signal. Data is held until the ACK signal is received 
from the initiator. The next data is then provided on the bus, 
and the process is repeated. When transferring data in the op- 
posite direction, the target asserts the REQ signal, indicating 
that it is ready to receive data. The initiator drives the data 
lines and then asserts the ACK signal. The initiator continues 
to drive the same data until the REQ signal goes false. The 
target then negates the REQ signal, the initiator provides new 
data, and the process is repeated. 

If the devices agree to the synchronous mode during the 
message phase, the target device does not wait for the ACK 
signal before sending the REQ signal for the next data. In- 
stead, the target may generate one or more REQ pulses ivith- 
out the corresponding ACK pulse received (up to a pre- 
agreed maximum known as the REQ/ACK offset). Upon 
generating all the REQ pulses, the target compares the num- 
ber of REQs and ACKs to verify that each data set was suc- 
cessfully received. To set up the synchronous data transfer, 
the devices establish a REQ/ACK offset (the maximum al- 
lowed number of REQs without corresponding ACKs re- 
ceived during the transfer) and the transfer period, Tlie trans- • 



Figure 2: Information-Transfer Phases 



MSG 





1 
1 
1 
1 



C/D 



1 
1 


1 
1 



I/O 


1 



1 



1 



1 



Phase Name 

DATA OUT 

DATA IN — 

COMMAND 

STATUS 

(reserved for future use) 

(reserved for future use) 

MESSAGE OUT 

MESSAGE IN 



Description 

Data sent from Initiator to target 
Data sent from target to Initiator 
Command sent from initiator to target 
Status sent from target to initiator 



Message from initiator to target 
Message from target to Initiator 



The AW Tech Journal 19 



Inside SCSI 



fer period determines the time between the end of one byte 
of data transmission and the beginning of another. (Figure 3 
illustrates bus phase flow,) 

SCSI-2 ENHANCEMENTS 

Although the original SCSI spec published in 1986 (SCSI- 
1) was a great stride forward, it was lacking in some key ar- 
eas. The SCSI-1 spec lacked sufficient definition to ensure 
compatibility between devices. The spec made reference to 
many different commands, but actually required the imple- 
mentation of only a single one (REQUEST SENSE). The re- 
sult was that different devices supported different com- 
mands, limiting the number of controllers that could "plug 
and play" in a particular SCSI system. Even as the SCSI-1 sp>ec 
was being finalized this limitation was recognized, and the 
Common Command Set (CCS) group was formed to solve 
this problem by putting together an extended subset of the 
SCSI commands. The commands were extended to allow 
more detailed information to be sent to and from the device. 
A subset of all of the possible commands was chosen to make 
it easier for the peripheral device manufacturers. Limiting the 
number of commands that a SCSI device must respond to in- 
creases the chance that all of them can be implemented. Al- 
though the CCS document was not incorporated into the 
SCSI-1 specification, it's principles were sound and it was 
recognized as a de facto standard to be followed by SCSI pe- 
ripheral manufacturers. This helf>ed to reduce the amount of 
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plug-and-play incompatibilities. 

The CCS principles were incorporated into the SCSI-2 spec- 
ification. SCSI-2 classifies commands as mandatory, option- 
al, or vendor-unique. SCSI de\'ices are required to implement 
at least all of the mandatory commands for their device types. 
Commands for direct access (disk drive), sequential-access 



SCSI Signal Definitions 

SCSI signals are carried on two sepi- 
arate cables. The A cable contains the 
18 signals defined in the SCSI-1 spec, 
and the B cable contains the new def- 
initions of SCSI-2, 29 in all. 11 signals 
are used for control, and 36 are used 
for data (including parity). (See Fig- 
ures 4 and 5 for the conductor as- 
sigments for the A and B cables, 
respectively.) 

REQ (request): Driven by a target 
to indicate a request for a REQ/ACK 
data-transfer handshake (for DB7-0). 

ACK (acknowledge): Driven by an 
initiator to indicate an acknowledg- 
ment for a REQ/ACK data-transfer 
handshake (for DBO-7). 

REQB (request): Driven by a target 
to indicate a request for a REQB/ 
ACKB data-transfer handshake (for 
DB31-8). 

ACKB (acknowledge): Driven by 
an initiator to indicate an acknowl- 
edgment for a REQB/ACKB data- 
transfer handshake (for DB31-8). 



ATN (attention): Driven by an 
initiator, 

BSY (busy): Wired OR signal driv- 
en by the initiator or target to indi- 
cate that the bus is being used. 

C/D (control/data): Driven by a 
target that indicates whether CON- 
TROL or DATA information is on the 

data bus. 

DB(7-0,P) (data bus 7 to and par- 
ity): On the A cable, these lines carry 
data back and forth between target 
and initiator. Also, each line is 
uniquely used by devices to an- 
nounce tlieir presence during bus ar- 
bitration. 

DB(31-8,P1,P2,P3) (data bus 31 to 8 
and parities): On the B cable, these 
lines carry data back and forth be- 
tween target and initiator. 

DIFFSENS (differential sense): 
Found only on a differential SCSI bus, 
this signal enables the differential 
drivers on the bus, 

I/O (input/output): Driven by a 



target that controls the direction of 
data movement on the data bus 
(with respect to the initiator). Also 
used to distinguish between Selec- 
tion and Reselection phases. 

MSG (message): Driven by a tar- 
get during the Message phase to in- 
dicate that the data contains message 
information. 

RST (reset): Wired OR signal that 
can be set by any device that resets 
the bus. This is normally done at 
power-up or when a requested device 
does not respond. 

SEL (select): Used during bus arbi- 
tration by an initiator to indicate that 
it wants to select a particular target, or 
by the target to reselect the initiator. 
The device to be selected is indicated 
on the data lines. 

TERMPWR (terminator power): 
Provides power so that termination 
resistors can be positioned at both 
ends of the bus. 
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(tape drive), printer, processor, write-once (optical disk), CD- 
ROM devices, scanner devices, optical memory devices, 
medium changer devices ("juke box"), and communications 
devices are defined. 

Another proposal of the CCS document that was included 
in SCSI-2 is the concept of reselection. In SCSI-1, when an ini- 
tiator sent a command to a target it would occupy the bus un- 
til the target had completed the command. In SCSI-2, the ini- 
tiator can disconnect from its target after a command has 
been issued. When the command is complete, the target ar- 
bitrates for the bus for the purpose of reselecHng the device 
that sent it the command. It can then complete the operation 
by sending back data and status information. Now that the 
the SCSI initiator no longer has to wait for the SCSI target de- 
vice to finish a command, it is free to send commands to oth- 
er target devices so they can be executed concurrently. 

This may be useful in a system that has more than one tar- 
get SCSI device, but the more common situation is needing 
to send another command to the same target device. The 
SCSI-1 spec allowed only a single command to be outstand- 
ing from an initiator to a logical device of a target SCSI con- 
troller. In the case of disk drives this could be inefficient. Sup 
pose, for example, a host CPU gets four separate requests 
from the operating system to read sectors that reside on tracks 
1, 50, 2, and 52. If it can accept only one command at a time, 
the drive will waste a lot of seek time as it goes back and forth. 
If, however, all four commands can be sent at once, the con- 
troller at the disk can optimize the seek time by reading them 
in the order of 1, 2, 50, and 52. Because the host CPU speaks 



to the devices on the SCSI bus in terms of logical blocks of 
data, it has no idea where (or how) the data is stored on the 
device. Therefore, it is impossible for the host CPU to opti- 
mize the command sequence before it is sent to the SCSI de- 
vice. This feature, called command queuing, has been adopt- 
ed in SCSI-2. (Up to 256 commands can be queued.) 

For a device to keep track of the many commands it queues 
up, a queue tag is assigned to each one, allowing each com- 
mand to be uniquely accessed. Once a device has been se- 
lected on the SCSI bus and the IDENTIFY message is sent, a 
two-byte QUEUE TAG message is sent. The message consists 
of the desired queuing function and the identifier of the ini- 
tiator. When a target controller reselects an initiator, the tag 
message is sent after the identifier. Commands sent without 
a queue tag are executed in the order recei\'ed, but only one 
can be outstanding, as defined under SCSI-1 standards (this 
is to maintain compatibility between queuing and nonqueu- 
ing environments). 

A third area of concern, SCSI-l's data-transfer speed, has 
also been improved in SCSI-2. SCSI-l's transfer rate maxed 
out at 5 MB/sec. This limitation was addressed from two dif- 
ferent angles. The most obvious method to speed things up 
was to add more bits. Today's common 16- and 32-bit pro- 
cessors give the impression that SCSI-l 's 8-bit bus is primi- 
tive. Consequently, the WIDE option was added in SCSI-2, 
adding 24 more data bits for a total of 32. The other method 
used to solve this problem was to speed things up. If you 
"wiggle" the lines twice as fast you will move data twice as 
fast— hence the definition of the FAST option of SCSI-2. > 
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Both methods of increasing the data throughput are not 
without their respective costs. Because all 50 pins of the SCSI- 
1 cable were already used, either the cable must grow or an- 
other cable must be introduced to add the additional data 
bits. Because SCSI-1 and SCSI-2 devices can co-exist in a sys- 
tem, increasing the size of the cable would make intercon- 
nections awkward. As a result, it was decided to add anoth- 
er cable. The original 50-pin SCSI cable is now known as the 
A cable, and the new 68-pin cable as the B cable. FAST SCSI 
has the limitation that it will work reliably only in a differ- 
ential SCSI bus implementation. Because the timing is tight- 
ened during FAST operation, single-ended FAST SCSI can- 
not keep up. FAST SCSI also requires that all components in 
the data path must support the higher data rates. 

The combination of FAST and WIDE SCSI provides a 
means to transfer data at a maximum rate of 40 MB/sec. This 
may seem impressive, but it's overkill for most of the com- 
mon applications of SCSI. After all, a disk can spin only so 
fast! SCSI devices do contain RAM memory buffers, and de- 
pending on how much and how intelligentiy the de\'ice stores 



data from a disk in RAM will determine how effectively the 
bandwidth can be utilized. You must also take into account 
the speed at which the computer system itself can "swallow" 
the data. Generally, it is wasted effort to go to the greater cost 
and complexity of adding FAST or WIDE SCSI if the host sys- 
tem cannot keep up. As an example, the DMA bandwidth of 
the Zorro II system bus in an Amiga 2000 has a maximum 
bandwidth of about 3.5 MB/sec. Therefore, a SCSI host 
adapter connected to the Zorro 11 system bus of an Amiga 
cannot even keep up with SCSI-1. The DMA interface to the 
host adapter of an Amiga 3000, however, is located on the lo- 
cal 68030 bus and is capable of speeds up to 50 MB/sec. 

COMMON ACCESS METHOD 

The SCSI bus hardware and software may be well defined 
as pertains to the physical and logical interfacing between ini- 
tiators and targets, but the interface between the SCSI host 
adapter in a computer system and the computer's operating 
system is not so clear. Because SCSI is implemented on many 
hardware platforms that have different system buses and dif- • 
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ferent hardware implementntions of the SCSI host adapter, 
there is a great need to mask differences with a standard soft- 
ware interface. Also, some hardware platforms make no pro- 
visions for the SCSI host adapter to be used with different de- 
vices attached to it. hi an effort to resolve these issues, an ad 
hoc industry committee called the Common Access Method 
(CAM) committee was formed. One goal of CAM is to pro- 
vide similar software interfaces across hardware platforms, 
minimizing the effort involved in creating device-driver soft- 
ware for a new system. 

Using the CAM approach, the operating system depen- 
dencies translate the system request into a CAM structure 
that is passed to the CAM model. Within the CAM module, 
the structure is translated into SCSI hardware instructions 
and a SCSI command. Upon completion of the command, sta- 
tus is then returned to the user application. 

SCSI'S PHYSICAL REQUIREMENTS 

The SCSI spec defines all the SCSI bus signals that need to 
pass between the devices. This signal information can be 
transferred via two methods: single-ended SCSI or differen- 
tial SCSI. (A particular SCSI bus implementation is either one 
or the other.) The logic level of a single-ended signal is de- 
termined by the voltage of a single wire compared to the 
common ground. A differential signal requires two wires, 
and its level is determined by comparing one of the wire's po- 
tential to the other. While re(.]uiring more complex interface 
drivers, differential SCSI is less susceptible to electrical noise. 
According to the spec, differential SCSI can be used for cable 
lengths up to 25 meters and a single-ended implementation 
is good for up to six meters. While differential SCSI may be 
appropriate when implementing a local area network (LAN) 
via SCSI, its added cost and complexity is usually not war- 
ranted in a system with a single host adapter. 

The SCSI spec requires a 50-conductor cable for the manda- 
tory A cable and a 68-pin cable for the optional B cable. Al- 
lowable connectors for the A cable come in several shapes: 
low-density shielded (which looks like a Centronics printer 
connector), low-density nonshielded {.l"x .1" ribbon connec- 
tor), and high-density shielded and nonshielded. The B cable 
connector may be only high-density shielded or liigh-densi- 
ty nonshielded. The high-density connectors were not de- 
fined for SCSI-1, but were necessary so that both connectors 
could fit on the back of even small peripherals that support 
the SCSI WIDE option. 

Internal connections for all SCSI host adapters for the Ami- 
ga conform to the low-density nonshielded standard speci- 
fied in SCSI. Connections to the outside world, however, do 



not follow the standard. Although the 25-pin cable used for 
external connections does handle all the signals required for 
a single-ended SCSI bus, 25 of the ground wires have been 
sacrificed in the interest of space. Because there are still six 
ground wires remaining, the cable does perform adequately. 
(As a side note, Apple also uses the 25-pin external connec- 
tor.) When attaching peripheral devices that conform to the 
standard connector, you wUl need adapter cables. 

To ensure that signal quality on the SCSI bus is maintained, 
termination of the bus is required at both ends. In general, all 
SCSI devices come with the resistor packs for termination in- 
stalled. If the device is not at either end of the cable, you should 
remove the resistors. More than two sets of termination resis- 
tors on the bus may cause the interface to fail, because the line 
drivers are not designed to handle the extra current. 

THE THIRD GENERATION 

Although SCSI-2 has not yet officially been put to bed, 
work is already underway to define the new features to be 
adopted in SCSI-3. 

Although the WIDE SCSI capability increased SCSI's band- 
width, the method in which it was implemented left many 
people unsatisfied. The issue of a single cable versus two sep- 
arate cables was a hot debate while SCSI-2 was being de- 
fined, and it still is. A compromise proposes that the 68-pin 
B cable be used as the primary cable providing a 16-bit data 
path and that an optional second 68-pin cable provide an- 
other 16 bits of data if desired. You could connect both the 
68-pin SCSI-3 and 50-pin SCSI-2 devices to the same cable, be- 
cause there would be nine new signals added to each side of 
the 50-pin connector. 

The ability to connect more than eight devices to the bus 
would be another nice addition. If the 68-pin cable becomes 
the standard, then eight more data lines will always be avail- 
able for asserting device IDs, allowing up to 16 devices. Fast 
data rates and increasing numbers of devices on the cables 
promise to tax the bandwidth (and reliability) of single- 
ended SCSI buses. To counter this, a suggestion is before the 
committee that differential SCSI become the only option. De- 
creasing the specified maximum length of single-ended ca- 
bles, however, may still make the 68-pin cable an option in 
compact systems. 

As an alternative to electrical cable to connect SCSI de- 
vices, some folks have suggested that optical driver technol- 
ogy be used. Optical driver technology has the advantages of 
reducing bulky cable interconnections and dramatically in- 
creasing the physical distance between devices. This some- 
what radical approach would require a dramatic departures 



Figure 6: A3000 SCSI Implementation 
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from the current bus concepts and definitions, however, and 
it is more likely a candidate for definifions a generation or 
more beyond SCSl-3. 

Another area being addressed is the concept of bus fair- 
ness. During bus arbitration, the device with the highest ID 
always wins out. This can leave devices with low IDs starv- 
ing to use the bus. Although prioritization of devices is some- 
times beneficial, some method needs to be provided to give 
the low priority guys a break once in a while. 

Finally, a concept analogous to the Amiga's autoconfig 



may find its way into the SCSI definition — automatic con- 
figuration of SCSI bus IDs. No matter which suggestions 
make the cut, you can be sure the SCSI standard will keep 
growing with the times. ■ 

Greg Berlin is an eight-year veteran of the Commodore engi- 
neering staff. He zuas one of the principal designers of the A3000 
hardware and is currently involved in the design of future high-end 
Amiga si/stems. Write to him cjo The AmigaWorld Tech Jour- 
nal, SO Elm St., Peterborough, NH 03458. 



The Amiga 3000 SCSI Host Adapter 



The A3000 uses a single-chip SCSI 
controller, the WD33C93, to construct 
the SCSI host adapter. The WD33C93, 
from Western Digital, contains its 
own microcontroller, which greatly 
reduces the overhead required in the 
system to manipulate and monitor 
the SCSI interface. The WD33C93 
pins connect directly to the SCSI bus 
to create a single-ended signal con- 
figuration. 

The host CPU side of the interface 
is handled by the Super DMA Con- 



troller (SDMAC) gate array on the 
A3000's motherboard. This device al- 
lows data to be sent via DMA off the 
SCSI bus into memory. As data comes 
in from the SCSI bus, it is stored in a 
small internal byte-wide FIFO in the 
WD33C93. As this HFO fills, the data 
is output to a 4-x-32-bit FIFO in the 
SDMAC chip. When its FIFO is full, 
the SDMAC requests the local bus 
from the 68030 and empties its FIFO 
into system RAM, 32 bits at a time. 
The bus is returned to the 68030 and 
the process is repeated until all the 
data has been received from the SCSI 



bus. (See Figure 6 for an illustration of 
the A3000 SCSI implementation.) 

The WD33C93 was designed to 
support the SCSI-1 implementation; 
therefore, WIDE SCSI is not support- 
ed. Pin-compatible versions of the 
WD33C93 that support some addi- 
tional characteristics of SCSI-2 are 
now available from Western Digital 
{WD33C93B). Although these devices 
do support FAST SCSI, it should not 
be used, since it requires a differential 
SCSI bus. 

—GB 
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The Basics of Ray Tracing 

Last issue's 3-D object viewer graduates 
to a higher level of sophistication. 

By Brian Wagner 



PHOTO-REALISM IS a popular catch phrase among com- 
puter graphics developers and users alike. One technique at 
the forefront of this explosion is ray tracing. From a pro- 
gramming standpoint, ray tracing is extremely elegant. With 
it, creating such dramatic effects as shadows, reflections, and 
even refractions (bending of light) is very easy. 

To illustrate the basics, t'il wa!k you through a small pro- 
gram (called tracer) that generates images of 3-D objects us- 
ing the ray-tracing rendering technique. Don't set your hopes 
too high: This is not a super-sophisticated ray tracer. I kept 
the example program simple, so the concepts would be as 
clear and understandable as possible. 

Before we begin, you need to know a few things about 
how tracer %vorks. The first consideration is the 3-D object for- 
mat it represents. For this example, I chose the GEO format 
introduced by VideoScape 3-D (Oxxi/Aegis). Because it is 
an ASCII format, you can create and edit the objects with just 
about any text editor or word processor. (For a full descrip- 
tion of the GEO object file format, refer either to the Video- 
Scape 3-D documentation or the ReadMe file in the Wagner 
drawer of this issue's disk.) To describe how to view the ob- 
ject, we give tracer another ASCII file. This viewing-descrip- 
Hon file will contain the following information: 

Where we are located 

Ttie position we are looking at 



Ttie fraction of ttie screen to use 

LIgtit source position 

View window size 

Position of the ground 

Center ot projection (eye location} 

In practice, of course, it will contain coordinates in 3-D 
space and numeric settings instead of words. For example: 

50 
000 
1.0 

- 50 so 50 
500 500 

250 

(For more details on the basic 3-D coordinate system — 
axes, planes, vectors, and so on — see "Building a 3-D Object 
Viewer," p. 15, June/July '91. In this article, we'll assume 
that the coordinate system is defined as shown in Figure 1.) 

The final option we need to send tracer is the size of the 
screen to use. We'll use values between 1 and 4 to represent 
the following screen resolutions (sizes): 

1 320x200 

2 320x400 » 




Hgure 1 : The 3-D coordinsle system. 



Figure 2: A pilot sees rellecled llglil rays passing through his windshield. 
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3 640x200 

4 640x400 

You will actually have more control over the image size 
because one of the vievving-description file's parameters de- 
fines which fraction of the screen to use. In other words you 
can specify, for example, that the program render in only 'A 
or 'A of the screen. 

Putting it all together, a sample tracer connmand line would 
look like: 

tracer objectflle viewflle screenmode 

If you want to skip ahead and look at the program now, feel 
free. Keep in mind, however, that the program itself only 
writes RGB files (.red, .gm, .blu), which must be converted 
into a picture for viewing. 1 included the pubhc domain pro- 
gram View in the Wagner drawer for doing so. (Refer to View's 
documentation for more information on viewing RGB files.) 

MODEL VIEWS 

To make some sense of the values in the viewing-descrip- 
tion file, let's define the model we will use to understand ray 
tracing. Imagine a pilot silting in his cockpit looking out of 
the windshield at the world. The only reason the pilot sees 
anything at all is that light (most likely from the sun) is re- 
flecting off the environment around him and then passing 
through the clear windshield into his eyes. (See Figure 2.) 

Granted, this is an extremely basic description of how we 
"see," But, as you will discover, it is exactly the approach to 
take when ray tracing a picture. Now, imagine that the 
plane's windshield is actually your computer's screen. When 
you sit and use your computer, you are the pilot looking 
through/at your windshield/screen. If we use this relation- 
ship, you can view anything that is on the far side of the 
monitor. 1 know, that would mean that our object would 
have to be inside the monitor to be viewed through the 
screen. As this isn't too feasible, we simulate this situation in- 
side the imaginary 3-D world of axes and planes. One way is 
to suppose that the windshield/screen is the XY plane, which 




XY P 
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VIEWER 



Figure 3: The windshield Is the XV plane; the pilot Is on tlie Z eiis. 
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Figure 4: Following every ray Irom ihe light source wastes a loi of effort. 
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Figure 5: Following sight rays back to Ihe source is more efficient. 

places the viewer somewhere on the Z axis. (See Figure 3.) 

The distance of the viewer from the XY plane is very im- 
portant and is specified in the viewing-description file as the 
center of projection (eye location). This distance effectively 
defines the "field of view," which can make the difference be- 
tween a flat-looking image or a fisheye effect. I will explain 
this value in more detail later. 

With this scenario, any objects that existed on the other side 
of the XY plane could be visible. I say "could be visible" be- 
cause the object is not necessarily "in view." (You'll see how 
this is determined a bit later.) 
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Figure 6; V/hun you score a sight^ray fiil, calculale tte lighl teaching the oblecl, 
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Figure 7: If the llghl source is blocked from the object, Ihe object has a shsdow, 

Remember, light reaching the pilot's eyes defines what he 
sees. In our case, we'll have a light source, which is specified 
in the viewing-desi:ription file, to shed light on the object. If 
we tried to simulate the true physics of light, we would have 
to follow large numbers of light paths as they left the Hght 
source. Firsl, we'd have to check if any of the paths hit the 
object, and then if any passed through the windshield/screen 



(or XY plane) to the viewer (from now on, I will refer to the 
XY plane as the "viewplane" and the viewer as the "eye"). It 
could take forever to chase random paths (rays) from the 
light source to see if they ever reached the eye, and only a 
small fraction of the light rays we followed would reach the 
eye at all. (See Figure 4.) 

This is where we reverse nature's process. Computer 
graphics ray-tracing algorithms are actually backwards ray 
tracers. Instead of tracing light rays from the light source, we 
will trace "sight" rays from the eye (viewer) backwards, 
through the viewplane (XY plane), into the scene, (See Fig- 
ure 5.) This %vay, we can determine exactly what is visible at 
any location on the viewplane. We will use the light source 
only when we actually hit the object with a ray. When we 
score a hit, we will calculate the amount of light that reach- 
es the point on the object. (See Figure 6.) 

Of all the trademarks that make ray tracing famous (shad- 
ows, reflections, and refractions), I will restrict the discussion 
to shadows, as they are the easiest to produce. Consider our 
example for determining the amount of light that reaches a 
particular spot on an object's surface. In the case of a shad- 
ow, light is blocked from the surface position being "shad- 
ed." To check for this, we test to see if anything lies between 
the surface point and the light source. If the light is blocked, 
the surface point gets no light and remains dark. That's it — 
instant shadows! (See Figure 7.) 

The remaining element in the vieiving-description file adds 
the final enhancements to our simple ray tracer — a ground 
and a sky. We will use the ground-level specification to de- 
scribe where the ground lies. The sky will be rendered ev- 
erywhere "above" the ground value. Although it may not 
sound like it right now, this really is a simple effect. 

STRUCTURED COMMENTS 

With the 3-D stage set, we are ready to examine the code. 
The first file, the header file tracer.h, contains all the structure 
definitions and a few constant definitions. For example, the 
Polygon structure below describes a single polygon: 

struct Polygon { 
SHORT cnt; 
SHORT -vtx; 
FLOAT nx, ny, nz; 

SHORT r, g, b; 

}; 

(Note: 1 assume that you are familiar with the concept of 
describing objects with polygons and vertices. If you are not, 
please refer to "Building a 3-D Object Viewer.") 

The first field, cnt, is the number of verfices in the polygon. 
The second field, *vtx, is an array containing indices into the 
list of the object's vertices. The next three fields, nx, ny, and 
nz describe this particular polygon's surface normal. Surface 
normals are simply direction vectors that define which di- 
rection the polvgon is facing. (We'll talk about this in more 
detail later.) The last three fields, r, g, and b define the color 
of the polygon as a mix of red, green, and blue. Each color 
value can range from to 255, 

Tlie next structure is the Vertex structure, which simply 
contains the XYZ coordinates of a point in 3-D space: 

struct Vertex { 
FLOAT x,y,z; 

1; • 
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Keep in mind that these locations are used to define 
a polygon's shape. 
We will use the third structure, Ray, to describe a ray. 

struct Ray { 

FLOAT ox, oy, oz; 
FLOATdx, dy, dz; 

}; 

It is really quite simple; rays need to have only a starting 
point and a direction defined. The first three fields define the 
ray's starting point in 3-D space, and the last three fields de- 
scribe the direction the ray travels from the starting point. 

Following Ray is the Triangle structure: 

struct Triangle { 
FL0ATx1,y1,z1; 
FLOAT X2,y2,z2; 
FLOAT x3,y3,z3; 
FLOAT nx, ny, nz; 

1; 

As you will see later, we can efficiently check to see if only 
a triangle and ray intersect. Therefore, we will break the ob- 
ject's polygons into triangles before testing for intersections. 
The Triangle structure holds these intermediate triangles. 
The first nine values define each of the triangle's three ver- 
tices, while the last three values define the triangle's surface 
normal. 

In turn, the Intersection structure holds information relat- 
ing to the intersection of a ray and a polygon (or triangle) 
when one occurs: 

struct Intersection { 
FLOAT ix, iy, Iz; 
FLOAT disi; 
VOID 'poly; 

1; 

The first three values define the exact location in 3-D space 
of the intersecfion. The distance from the eye to the intersec- 
tion point is stored in dist. Tlie final field is a pointer to the 
Polygon structure of the polygon that was hit. 

The three values in the Color structure: 

struct Color { 
SHORT r, g, b; 

}; 

define the polygon's color as described earlier. 

Finally, the ViewOpts structure holds all the information 
in the viewing-description file: 

struct ViewOpts { 

FLOAT cax, cay, caz; 
FLOAT Ipx, Ipy, Ipz; 
FLOAT scl; 
FLOAT Isx, Isy, Isz; 
FLOAT vpx, vpy; 
FLOAT wdy; 
FLOAT cpd; 

1; 

The first three fields define where the eye is located, and 

the following three define the position in 3-D space at which 
the eye is looking. The scl field describes which fraction of the 
screen to use. We'll use this value to scale the width and 
height of the screen mode specified in the command Une, let- 



ting us create images that cover, for example, only 'A, 'A, or 
Vs of the screen. This feature allows the user to generate quick 
test images. The next three fields define the location of the 
light source. The location of the light source in relation to the 
object determines which portions of the object appear light 
and which appear dark. The vpx and vpy fields hold the ac- 
tual width and height of the viewplane. These values, among 
other things, control zooming or how large or small the ob- 
ject appears. 

The wdy field houses the ground's position on the Y axis. 
We need only a single height value because the ground is an 
infinitely large plate that lies parallel to the XZ plane. The last 
field, cpd, is the eye's distance from the viewplane or how far 
the eye is from the XY plane on the Z axis. (Remember that 
we decided the viewplane is the XY plane and the eye is at a 
point somewhere on the Z axis.) 

TYING IT ALL TOGETHER 

The program begins in the tracer.c file. First it checks that 
the user specified the correct number of arguments. If the 
user did, tracer opens the Graphics and Intuition libraries, 
then allocates buffers to hold the polygons and vertices of the 
object. Next, the program allocates the three RGB buffers, 
one for each primary color, red, green, and blue. As we trace 
rays through each pixel on the screen, the color that results 
will be stored in these three buffers. 

Following all buffer allocations, the program opens the 
screen and window, sets the color palette, and removes the 
title bar. The screen will have only two colors — black and 
gray. As we trace through the pixels, tracer turns them gray 
on the screen to indicate that they have been processed. We 
remove the title bar because we need to see the entire screen. 

As a final preparation, the program initializes a few glob- 
al variables. We set npoly and nvert to zero because the ob- 
ject has yet to be loaded. Then we set gnx, gny, and gnz to 
indicate a vector pointing straight up the Y axis to initialize 
the ground as lying in the XZ plane. 

Now we are ready to load the object- and viewing-de- 
scription file. First tracer calls the loadobjectO function and 
passes it the first argument the user specified in the com- 
mand line (the object file's name). As the actual loading code 
is fairly straightforward, we won't waste any time going over 
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Figure 8: 'four viewer can by anywhere in 3-D space. To display !he view, rotate the scene. 
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Figure 9: The surface normal ol a polygon face. 

it. The program loads the viewing-descripHon file and places 
it in the global vopts structure by calling loadvoptsO. 

With ever)'thing opened, allocated, and loaded we can be- 
gin the rendering process, which is broken down into four ma- 
jor functions. The first to be called is transformO (located in 
math.c). In it, the object, light source, and ground normal are 
all transformed into the viewplane coordinate system. This is 
a little tricky, so pay close attention. Remember that we are 
using the XY plane as the viewplane, but you can specify 
where the eye is located in 3-D space, and it could be looking 
at any other location in 3-D space. (See Figure 8.) 

If we always use the XY plane as the viewplane, we need 
to rotate/ move the object, light source, and ground normal 
to get the same view of the object from the XY plane as we 
would from the arbitrary location in 3-D space. If you don't 
fully understand this concept, don't worry. It should become 
more clear as we continue. Keep in mind that this operation 
greatly simplifies the actual ray-tracing process. (We won't 
dig into the actual details of this function, as you can find a 
detailed explanation in "Building a 3-D Object Viewer.") 

After the transformation is complete, tracer calls calcnor- 
matsO (in math.c). This function steps through each of the ob- 
ject's polygons and calculates the polygon's surface normal 
using the vector cross-product operation. (Again, the details 
of this process can be found in the previous article. For now, 
it is important to know ordy that surface normals are simply 
direction vectors that indicate the direction in which a poly- 
gon faces. See Figure 9.) 

FIND THAT RAY 

Lef s begin ray tracing by calling the traceimageO function 
(located in image.c). Notice that tracer passes this function a 
pointer to our window's rastport. We will need this to turn 
the pixels gray as they are traced. The rather complex formula 
that leads off the function: 

ar = (scrw * ((scrh * 4.0) / (scrw * 3.0))) / scrh; 

calculates a scaling value used to compensate for the fact that 
monitors are not square. This difference in width and height 
is indicated by the aspect ratio. The above formula uses an 



aspect ratio of '/\ which is common to most monitors. 

Next, the program moves the width and height of the view- 
plane out of the global vopts structure and into the local vpx 
and vpy variables: 

vpx = vopts.vpx ■ ar; 
vpy = vopts.vpy; 

Notice that the width is scaled by the aspect ratio value. 
The width and height values (which originally come out of 
the viewing description file) are very important. When we 
start tracing, we are going to shoot rays through each pixel 
on the screen out into 3-D space. Therefore, we need to relate 
the screen size (in pixels) to an equivalent in the 3-D world. 
The exact values used are actually dependent on the size of 
the numbers that describe the object, 

As a general rule, the width and height should be equal (as 
specified in the viewing-description file) and about 'A the 
largest dimension of the object. For example, if the largest ob- 
ject dimension were 1000, a good width and height would be 
500. These values can, of course, be larger or smaller. In fact, 
you can use them to zoom the final image in or out. Smaller 
values will make things appear larger, while larger values 
will make things look smaller. 

Tlie next two lines calculate exactly how many pixels will 
be traced: 

actw = scrw * vopts.sci; 
aclh = scrh ' vopts.sci; 

Here we use that scaling value from the viewing-descrip- 
Hon file to scale the original width and height of the screen 
(in pixels). Finally, we set the dravring color to pen number 
one — gray. 

We begin tracing by starting two loops, one for the width 
and the other for height. This will allow us to cover the spec- 
ified range of pixels by working top to bottom, left to right. 
Each pixel is handled on an individual basis. The beauty of 
the ray-tracing algorithm is that it deals with each pixel, one 
at a time. Instead of examining the object's polygons and fig- 
uring out which pixels to set to which color, the program 
goes backwards and looks at the pixel first. 

We want to create a ray that starts at the eye and passes 
through each pixel. Because our screen full of pixels is rep- 
resented in 3-D space by the XY plane, this is very simple: 

px = (FLOAT)l+0.S; 

px = vpx * ((px / actw) - 0.5); 

py = (FLOAT)(acth - 1 - j) - 0.5; 
py = vpy • ((py / aclh) - 0.5); 

The first tvvo lines find the horizontal, or X-axis, position. 
The last two find the vertical, or Y-axis, position. Because 
they are very similar, we will examine the first two lines only. 

px = (FLOAT)! + 0.3; 

adds 0.5 to the pixel's X coordinate because we want to deal 
with the center of the pixel. 

px = vpx * ((px / actw) - 0.5); 

converts the pixel location into the range of 0.0 to 1.0 by di- 
viding the pixel's X coordinate by the total number of pixels 
to be traced horizontally. Subtracting 0.5 from this value en- 
sures that it falls in the range of - 0.5 to 0.5, Finally, we mul- 
tiply by the viewplane width (stored in vpx). > 
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The same process produces the Y-axis position in 3'D space. 
The difference is that the position is reversed because vertical 
screen coordinates are reversed from those in 3-D space. 

With the pixel's location in 3-D space stored in px and py, 
lef s build a ray. First, we calciJate it's origin. Simple: The ori- 
gin is the eye position and the eye lies on the Z axis. There- 
fore, the X and Y coordinates are both zero. The Z coordinate 
is set to the center of projection (eye location) specified in the 
viewing-description file. Remember, because the viewplane 
is at the center of the Z axis (0), this value specifies distance 
from the viewplane. (See Figure 10.) 

With the origin set, we calculate the ray's direction. Be- 
cause the direction will be from the ray origin through the 
previously calculated pixel location, we create a vector by 
subtracting the ray's origin from the pixel location. After con- 
verting this vector into a unit vector (a vector with a length 
of 1), we store the ray direction in the Ray structure. 

FOLLOW THAT LIGHT 

Now that we have a ray, we can "trace" it and see what, if 
anything, it hits. First, the program initializes the intersection 
structure, isec, to indicate that there is currently no hit. Then 
it loops through all of the polygons and, by calling the poly- 
gonhitO function (in mnth.h), tests to see if the ray intersects 
any of them. 

At the heart of every ray tracer is the code that tests for in- 
tersections between a ray and some shape — in our case, a tri- 
angle. Because our polygons can be larger than triangles, 
however, we must also test the polygon in triangular pieces- 
for intersection. The polygonhitO function does the neces- 
sary break-ups and calls the trianglehitO function (also in 
math.h) to check for intersection. (See Figure 11.) 

The code that performs the triangle/ray intersection test is 
quite complicated, so we will go over it on a basic level only 
(study it at your own pace). First, the ray is checked to see if 
it intersects the plane in which the triangle lies. If so, the rou- 




Figure 11: Break a polygon inio triangles belore lesting lor lay interseclions. 
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Figure 1Q : The center 01 projection specilles the eye location and lis distance hom the viewpltne. 



Figure 12:Checkloragioun(lhit,lhenany objects thai block the light. 

tine checks to see if the intersection point is either behind the 
ray origin or if it is beyond an intersection already found. Re- 
member, we want to end up with the closest intersection. If 
the intersection is found to be "good," the routine concludes 
by determining whether this intersection point actually lies 
inside the triangle. If the answer is yes, the intersection point 
and distance is stored in the supplied intersection structure 
and the function returns. 

All the polygons are checked in this manner. After the ray 
is checked for intersection with all the polygons, it is checked 
to see if it intersects the ground, via the groundhit() function 
(in math.h). This function is really the same as the first part 
of trianglehitO. The ray needs to be checked only to see if it 
intersects the XZ plane at the Y-axis location specified in the 
vievidng-description file. In addition, ground hitO returns true 
only if the intersection is closer than any of the triangle/ray 
intersections. 

If a ground hit is found, the ground will appear at that pix- 
el, so it needs to be shaded. The first step in this process is to 
check if this point lies in shadow. To test this, we call shad- 

Contimied on p. 63 
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Official Words from CATS 

In response to the often-heard statement "What this mar- 
ket needs is consistency across applications" comes the Ami- 
ga User Interface Style Guide. Written by CATS, it describes 
how an apphcation's user interface should look and operate, 
setting forth Commodore's interface standards for the Work- 
bench, the Shell, and ARexx. The guidelines are backed by 
definitions, descriptions, and illustrations of each of the in- 
terfaces. As only behavioral guidelines are presented, both 
creatively and technically minded interface designers can 



benefit. If you can't wait to find a bookstore, you can order 
the Ainign User Interface Style Guide directly from Addison- 
Wesley Publishing Company (Jacob Way, Reading, MA 
01867/800/447-2226) for S21.95 ($28.95 in Canada). 

For hardware-minded registered developers, CATS is of- 
fering an Amiga 3000 schematics manual for S35 (plus S2.50 
for Canadian shipping, $5.00 for overseas). Direct your re- 
quests to CATS Orders, 1800 Wilson Dr., West Chester, PA 
19380 and ask for part number 314677-02. 



Be a Winner 

Want to win $10,000? If 
you are working on (or have 
finished) a program or de- 
vice that would benefit the 
physically or learning dis- 
abled, here's your chance. 

Johns Hopkins University 
is conducting a National 
Search for Computing Appli- 
cations to Assist Persons 
with Disabilities (CAPD). 
Sponsored by the National 
Science Foundation and MCI 
Communications Corp., the 
National Search is a compe- 
tition for ideas, systems, de- 



vices, and software that are 
creative and affordable solu- 
tions to the problems faced 
by the disabled. The grand 
prize for the best computer 
program or device is $10,000, 
and over 100 additional 
prizes will be awarded. Re- 
gional winners will be select- 
ed in December at science 
museum exhibitions across 
the country. 

The top 30 regional win- 
ners will be invited (all ex- 
penses paid for the top 10) to 
exhibit at The National Exhi- 



bition at the Smithsonian In- 
stitution in Washington, DC, 
on February 1 and 2, 1992. 
There the grand prize winner 
and top 10 national winners 
will be honored. 

Entry fliers are available 
from CAPD, PO Box 1200, 
Laurel, MD 20723. The dead- 
line for entries is August 23, 
1991, but don't let the short 
timeframe deter you. Nation- 
al Search officials promise to 
expedite last-minute entries 
by fax or other means when 
necessary. 
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Compatible with CDTV and ISO-9660-type CD-ROM 
drives, the Fred Fish Collection on CD-ROM disc houses 
410 floppies worth of the Fred Fish software library. The col- 

lection is provided both in its original form organized by I'Q.Ster/ I'aSter 
disk and, as a bonus for BBS sysops, compressed by disk 
into .zip files. Several tools (including SID and PKAZIP) are 
included in the disc's root directory to facilitate file man- 
agement. Available from HyperMedia Concepts Inc. (PO 
Box 85303, Racine, Wl 53408, 414/632-3766), the Fred Fish 
Collection on CD-ROM sells for $69.95 (plus $2.00 shipping 
U.S., SIO foreign). As the collection expands, registered 
users may purchase updates every four months for $29.95 
each. If you prefer to plan ahead, consider a subscription: 
$109.95 for the original disc and two updates. If you are a 
registered Amiga developer, call HyperMedia Concepts 
about their discount plan. 



Great Valley Products wants to speed up your Amiga with 
its Series II accelerator systems. Topping the line, the GVP 
A3050 ($2999) is a 50 MHz 68030 accelerator board that comes 
populated with 4MB of 32-bit memory (expandable to 32MB), 
and a SCSI controller. Available optional drives are the Max- 
tor one-inch tall 120MB model or a half-height 340MB mod- 
el. GVP also offers 22 MHz and 33 MHz 68030 models. The 
22 MHz board comes standard with 1 MB of RAM and can be i 
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expanded to 13MB, while the 33 MHz version is shipped 
with 4MB of RAM and can be expanded to 16MB. For com- 
plete pricing, contact Great Valley Products, 600 Clark Ave., 
King of Prussia, PA 19406, 215/337-8770. 
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Where's the Tail? 



Tired of the same old input 
devices? Consider the Air- 
Mouse Remote Control 

($595), a bidirectional in- 
frared, point-and-click input 
device. Designed with pre- 
sentation software and CDTV 
titles in rrdnd, the two-button 
remote unit will work up to 
seven meters from its base- 
station, which connects to 
your CPU via the serial port. 
Current drivers support OS 
1.3 and CDTV, but a 2.0 driv- 
er is on the way. 

Should you have a special 
implementation in mind, 
check out the Developer 
TooIKit. For S4995 you receive 
a developer-styte AirMouse 
remote and basestation, plus 




PoinI and click Irom seven melers away. 

drivers for the Amiga, MS- 
EXDS, Windows 3.0, and Mac- 
intosh 6.0.x. If you have any 
problems, Selectech provides 



developer services. Contact 
Selectech Ltd., 30 Mountain 
View, .Colchester, VT 05446, 
802/655-9600. 



Cheat Sheets 



You went to the trouble of programming keyboard equiv- 
alents for menus choices, but now your users complain they 
can't remember the commands. Rather than hire a larger 
technical-support staff, consider K/B Optimizer custom 
keyboard templates and reference cards. Templates and 
cards are constructed of high-impact, UV-rated polypropy- 
lene plastic and coated with a waterproof, scratch-resistant 
plastic matte finish to elimnate glare. If none of their stan- 
dard configurations will do, K/B promises to custom design 
templates and cards to your specifications. Pricing depends 
on quantity, ranging from $24 apiece for 10 templates 
($29.95 apiece for 10 cards) to $5.35 each for 1000 templates 
($9.95 each for cards). For exact prices and more details, 
contact K/B Optimizer, PO Box 877, Gardiner, MX 59030 
406/848-7320. 



Faster and Sharper 

If the standard Amiga display modes aren't enough for 
your software, consider Digital Micronics Inc.'s 60 MHz 
DMIOIO ($1095) and DMI020 ($1995) graphics processor 
boards for the A2000, A250C), and A3000. Both offer pro- 
grammable control up to their maximum resolutions 
(1024x800 for the DMIOIO, 1280x1024 for the DMI020). The 
DMIOlO's eight-bitplane system uses a 24-bit, 16-miIlion-col- 
or palette with 256 active colors and over 800,000 available 
pixels, while the DMI020's 24-bitplane system offers 16 mil- 
lion colors and over 1,3 million pixels. If that's sttH not enough 
power, the DMIOIODB ($195) memory buffer option for the 
DMIOIO promises to increase display speed or up resolution 
to 1280x1024, The DMI020's memory buffer option 
(DMI020DB, $595) doubles the available VRAM to speed up 
screen display. For further information, contact Digital Mi- 
cronics Inc., 5674-P EI Camino Real, Carlsbad, CA 92008, 
619/931-8554. 
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Pass the Word 



Run across any hot products, 
PD sofhoare, or neios? We luaiit 
to here about it. Send the details 



to TNT, The AmigaWorld 
Tech Journal, 80 Elm St., Pe- 
terborough, NH 03458. m 
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This nonbootable disk is divided into two main directories, 
Articles and Applications . Articles is organized into subdirec- 
tories containing source and executable for all routines and 
programs discussed in this issue's articles. Rather than con- 
dense article titles into cryptic icon names, we named the 
subdirectories after their associated authors. So, if you want 
the listing for "101 Methods of Bubble Sorting in BASIC," by 
Chuck Nicholas, just look for Nicholas, not lOlMOBSIB. The 
remainder of the disk, Applications, is composed of direc- 
tories containing various programs we thought you'd find 
helpful. Keep your copies of Arc, Lharc, and Zoo handy; 
space constraints may have forced us to compress a few files. 



With the exception of the 2.0 include fdes (which are dis- 
tributable only under license), the supplied files are freely dis- 
tributable. Do not, however, resell them. Do be polite and ap- 
preciative: Send the authors shareware contributions if they 
request it and you Uke their programs. 

Before you rush to your Amiga and pop your disk in, make 
a copy and store the original in a safe place. Listings provid- 
ed on-disk are a boon until the disk gets corrupted. Please take 
a minute now to save yourself hours of frustration later. 

If your disk is defective, return to Amiga Worid Tech Jour- 
nal Disk, Special Products, 80 Elm St., Peterborough, NH 
03458 for a replacement. 
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RxTools \ #^ 

Where ARexx meets Intuition. 

By Eric Giguere 



AREXX, THE INCREASINGLY 
popular interprocess-control protocol 
that Commodore adopted under 
AmigaDOS 2.0, is a faithful Amiga 
implementation of the powerful REXX 
language. Because REXX was de- 
signed for console-oriented systems — 
not graphical user interfaces like the 
Amiga's — it comes as no surprise that 
ARexx lacks windowing and menuing 
functions. Thanks to ARexx's expand- 
ability, however, you can add Intu- 
ition-like capabilities to your ARexx 
scripts. 

There are two ways of adding func- 
tions to ARexx. The most common 
method is to use an ARexx function 
library, which is an Amiga shared 
library that ARexx can access. (The 
ARexx mathematics library, Rexx- 
MathLib, is an example of a function 
library.) An often easier method is to 
use an ARexx function host. A func- 
tion host is simply an ARexx-compati- 
b!e application program capable of 
processing special messages from 
ARexx. TTR Development's RxTools 
package is such a program. 

The RxTools software comes on a 
single bootable disk that includes not 
only the host, but also an extensive set 
of tutorial files and a simple RxTools 
script. To use RxTools, you need ei- 
ther Workbench 2.0 or Workbench 1.3 
along with the ARexx software pur- 
chased from William Hawes. You 
should have at least one megabyte of 
memory, as the function host itself is 
almost 400K in size. A hard disk is 
also recommended. If you wish to 
share your RxTools scripts with oth- 
ers, they too must buy the package. 

To access RxTools' functions, you 
must run the rx_tools.exe program in 
the background. RxTools provides an 
initialization sequence that your 



ARexx scripts can use to find out 
whether the function host is running, 
and to start it if not. The initialization 
sequence also adds the function host 
to the ARexx Library List (the list of 
all function libraries and function 
hosts that are active) so that ARexx 
will send it a message when it needs 
to locate a function. 

BUILDING WITH OBJECTS 

RxTools is based on the principles 
of object-oriented programming 
(OOP). There are many books that 
describe OOP in detail, but here's a 
quick primer: The basic entities in 
OOP are known as objects. In RxTools, 
for example, a vN'indow is an object. 
Objects have certain attributes; a win- 
dow has a size and a position, for 
instance. Objects also allow you to 
modify those attributes through vari- 
ous methods; RxTools provides a 
method to move a window, for exam- 
ple. A method can be thought of as a 
procedure or function call, but one 
that is intimately associated with — 
actually a part of — an object. 

Methods and attributes are not very 
interesting without another (X)P 
feature known as class inheritance. 
Each object is a member of a class of 
objects. All objects in a class share 
attributes and methods, though of 
course each object has its own data 
space. For example, two windows 
both have a movement method, and 
both have size and position attributes, 
but the values of the two sets of at- 
tributes may be different. You can 
build nev\' classes out of old classes 
simply by adding or modifying at- 
tributes and methods. Each child class 
inherits the attributes and methods of 
its parent class unless the new class's 
definition specifically overrides them. 
In RxTools, for instance, the console 
class is a child of the window class. 
Hence, a console object has all the 
capabilities of a window object plus a 
set of methods specific to creaHng and 
using an Amiga console device. Class- 
es also have methods, but these are 
used mostly to create new objects. 
Although object-oriented program- 



ming seems strange at first, if you 
play around with it for a while, you 
will likely find it to be quite elegant. 
To be truly elegant, however, OOP 
requires a programming language 
designed with objects in mind. While 
ARexx is not an object-oriented lan- 
guage, RxTools manages to get 
around that restriction. RxTools in- 
cludes a reasonable set of object class- 
es: menus, various classes of windows 
and consoles (including a functional 
text editor), file requesters, and some 
basic gadgets. 

Let's dissect a simple RxTools script 
to get a better feel for the program. AH 
RxTools scripts start with the follow- 
ing statement: 

r An RxTools Script v 
interpret getcllp( Yxtoolsinll' ) 

This rather strange statement does 
two things; It retrieves a string from 
the ARexx Clip List and then uses the 
INTERPRET instruction to execute the 
contents of the string as if they had 
been typed into the script. Tlie string it 
retrieves must have been previously 
installed in the Clip List by executing 
the rxtools.rexx ARexx script, which, 
as you will recall, also starts the Rx- 
Tools function host. The string holds a 
series of ARexx statements that per- 
form various initialization tasks, in- 
cluding ensuring that the RxTools 
function host is still alive (in case a 
pre\dous script has terminated it), 
opening a notification port, and assign- 
ing useful values to a set of variables. 

The next step is to open a window 
by calling the RxTools function host: 

my_wlndow_send('r)(_console',_OPEN, 
10, 30, ,250, 80, 'My Window' ) 

(Keep in mind that if you want to split 
an ARexx statement across two or 
more lines, each line except the last 
one must end with a comma. Such 
commas are skipped by the inter- 
preter, so the example above really has 
seven parameters, not eight.) 

The _send() function is an RxTools 
function that "sends a message" to a 



M AugustlSeplember 1991 



class. In RxTools terms, sending a 
message to a class or object means 
invoking a method on that class or 
object. Do not confuse tliis with the 
Amiga's built-in interprocess commu- 
nication (IPC) facilities. In this case, the 
_send() function is invoking the 
_OPEN method of the rx_console 
class, with four integers and a string as 
parameters for that method. This will 
create (open) a window of class 
rx_console at location (10,30), width 
250, height 80, and title "My Window" 
on the Workbench screen. The re- 
turned string is a handle identifying 
the newly created window. 

Once the window has been opened, 
you can display a string of text in it by 
using the following function call: 

call send my_wlndow, _PUT_STRING, 
'Hello world' 

(The call instruction is used to invoke 
this function because the return value 
is unimportant.) Notice how this time 
we use the send( ) function instead of 
_send(). The leading underscore 
makes a difference: _send() invokes a 
method on a class, whereas sendO 
invokes a method on an object. This 
particular sendO sends a _PUT_ 
STRING message to the window ob- 
ject just created. PUT_STR1NG takes a 
string and outputs it at the current 
cursor location. 

Now we come across another of 
those interesting INTERPRET 
statements: 

interpret gelcllp{ 'rx_tools_ewent_handler' ) 

This retrieves and executes another 
string from the Clip List. This particu- 
lar string waits for messages (of the 
IPC type) to arrive at the script's noti- 
fication port, calls a function in the 
script, and then watts for another 
message to arrive. Any statements 
following the event handler (the 
INTERPRET statement) will not be 
executed unless they are part of an 
ARexx function. 

What kind of messages does the 
notification port receive? It depends 
on the objects that the script defines. 
For example, most windows send a 
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An Inluilion inlertice lor Zoo by RiToois. 

CLOSEWINE>OW message when the 
user clicks the window's close gadget. 
The event handler receives this mes- 
sage and immediately calls the 
CLOSEWlNE>OW() function, which 
might be defined as foUows; 

CLOSEWINDOW: procedure expose packet 
parse arg the_window 

call send thewindow, CLOSE 
call send the_wlndow, DELETE 
call reply packet, 
exito 

This routine closes and deletes the 
window that received the close event, 
and then terminates the ARexx script. 
(A script that opens several windows 
would include code to exit only if all 
windows have been closed.) Most 
object definitions include, as a param- 
eter, the name of a function that is to 
be called when an event for that object 
occurs. For example, you could add a 
string gadget to the window using the 
statement: 

call send my^window, _ADD_STRING 
GADGET, 'StringGadget', ,10, 10, 100 

When the user enters a string in the 
gadget and presses RETURN, the 
event handler receives an event and 
calls the StringGadgetO function, 
which can then retrieve the string 
from the gadget and process it. An 
RxTools program is basically just a 
collection of ARexx functions that get 
called whenever events occur. 

That, in a nutshell, is the skeleton of 



an RxTools program: Initialize Rx- 
Tools, define and initialize all the ob- 
jects, define the functions that the ob- 
jects call, and then start the event loop. 

CLIMBING AND BROWSING 

The set of all classes in an OOP 
environment forms what is known as 
a class hierarchy, or tree, because 
every class is ultimately a descendent 
of some root class. This hierarchy is 
important because it lets the program- 
mer quickly determine how the vari- 
ous classes are related. You will find a 
class tree at the back of the RxTools 
documentation. 

A good OOP environment includes 
a class browser, a tool that allows the 
programmer to traverse the class tree 
and view specifics about each class. 
The RxTools browser shows the inher- 
itance path of a class and the methods 
that class and its objects support. 

The browser is the most powerful 
tool you can use to write RxTools 
scripts because its information is com- 
plete and up-to-date. The only prob- 
lem with the browser as it now stands 
is that there is no simple way to cap- 
ture its output. Because of the way it 
was implemented, all its output is 
generated by the function host itself 
and hence appears only on the console 
where the function host was started. 
This limitation is a bug that 1 hope 
will be fixed for the next update. 

RxTools has other problems as well, 
the most serious of which is its docu- 
mentation. Not only is the 90-page 
manual meager and incomplete, but it » 
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is poorly organized, full of errors, and 
lacks an index. The explanations need 
to be expanded to describe in detail 
what a function host is and how Rx- 
Tools does its work. My recommenda- 
tion: Once you have installed and 
started RxTools, leave the manual in 
its box. Use the tutorial examples and 
the class browser as learning tools 
instead. 

Instalhng RxTools is also trouble- 
some. The installation procedure 
assumes you want RxTools installed 
on your SYS: volume, a mistake if the 
partition is almost full. An installation 
script written in ARexx would be 
more flexible, and the ultimate goal 
should be an installation script that 
uses RxTools lo install itself. Another 
problem is that RxTools does not 
always clean up after itself. It is not 
uncommon for an ARexx program 
under development to encounter an 
error and terminate. Unfortunately, 
RxTools does not free the program's 
resources, and so its windows and 
screens hang around until RxTools 
notices there is no ARexx program to 
notify. Even when RxTools is told to 
terminate, orphaned screens are often 
left behind to eat up valuable chip 
memory. Resource tracking needs to 
improve. 

RxTools' error messages are annoy- 
ing. Warning and minor error mes- 
sages are displayed in system 
requesters, and, under 1.3, the buttons 
on the requester overlap with the last 
line of text. Serious errors are 
announced using the red-on-black 
alert requesters, which seem incredi- 
bly rude (and reminiscent of a GURU 
message) when you consider that at 
most the RxTools function host will 
crash. (This is not an unlikely occur- 
ence, either. I found that some of the 
RxTools tutorial scripts crash the 
function host.) 

RxTools could use a few more ob- 
ject.s, including list boxes and horizon- 
tal scroll bars. I would also like to see 
some support for the new 2.0 gadgets, 
windows, and screens — even if those 
features are not available to 1.3 users. 

Finally, I would like to see RxTools 
decreased in size, or at least have 
access to a smaller, nonbrowsing 
version. The current size almost cer- 
tainly precludes its use in developing 



commercial products, 

FUTURE DIRECTIONS 

RxTools is an interesting product 
that is almost crippled by bad docu- 
mentation and bugs. That's a shame, 
considering how much work has gone 
into the design and implementation of 
the function host. To UK's credit, 
however, the company has been quick 
to answer questions on BIX and has a 
BBS (608/277-8072) for making up- 
dates and bug fixes available to users. 
TTR is planning to fix many of Rx- 
Tools' problems, and to revamp the 
manual. At this stage, however, it's 
hard to recommend RxToots to the 
novice ARexx user. It would be wise 
instead to wait for the bug fixes and 
the new documentation. 

In the meantime, you might want to 
look at the RexxArpLib function li- 
brary available on BIX or the Fred Fish 
disks. It provides many of the same 
capabilities, albeit in a different and 
much more restricted manner. It is, 
however, a good way to play around 
with ARexx and Intuition, and it can 
help you to decide whether RxTools is 
for you. 

RxTools 

TTR Development 

1120 Gammon Lane 

Madison, Wl 53719 

608/277-8071 

S54.95 

One megabyte required. 

AmeegaView 

Routine help for C. 

By David T. McClellan 

WRrriNG A PROGRAM that pro- 
vides a highly interactive GUI inter- 
face can be a sticky proposition. 
Intuition is function-rich and corre- 
spondingly complicated to write for. 
ACDA Corp.'s AmeegaView (former- 
ly AmigaView) is designed to make 
the environment easier to program in 
by making certain common operations 
simple and to provide consistent 
looks-and-feels for applications. 

AmeegaView consists of a set of 
libraries, include files, demos, and on- 
disk documentation for Intuition, IFF, 
and graphics functions to call from 
SAS/C and MANX Aztec C programs. 
ACDA didn't address Modula-2; 
Benchmark and the other packages 



have their own simplified libraries. 
AmeegaView claims to run with Lat- 
tice C 5.02 and 5.04 (which became 
SAS/C as of 5.10), and Aztec C68/k 
3.6a through 5.0b. The documentation 
comes on disk, designed to be printed 
out as you see fit. 

The functions deal with familiar 
Intuition objects (screens, windows, 
menus, gadgets, and so on), as well as 
fonts, polylines, bitmaps, IFF images, 
and the like. The difference between 
Intuition and AmeegaView is the 
approach. With Intuition 1 .3, to open a 
screen and a window and add some 
custom gadgets and menus, I have to 
fill in values on numerous large C 
structures and then call several Intu- 
ition functions to build the user inter- 
face. Using AmeegaView, I can cut out 
most of the data-structure initialization 
and some of the calls — the Ameega- 
View routines fill in the defaults for 
me, while allowing me to customize 
those I want. For example, here's an 
Intuition window-open as compared 
to the AmeegaView version: 

I* Intuition version */ 

struct IntultlonBase 'IntultlonBase; 
struct Screen LDraw_scr; 
struct NewWindow newwin; 
struct Window *LDraw_win; 

r Open Intuition library, screen, allocate 
bitmaps, then */ 

newwIn.LellEdge = 0; 
newwIn.TopEdge = 0; 
newwin. Width = WIDTH; 
nevnvin.Height = HEIGHT; 
newwin.DetallPen = WHITE; 
newwin.BiockPen = BLACK; 
newwtn.lDCMPFIsgs = CLOSEWINDOW | 

GADGETUP I MENUPICK | 

MOUSEBUTTONS; 
newwIn.Flags = WINDOWDEPTH | WINDOW 

CLOSE I SUPER_BITMAP | 

BORDERLESS | ACTIVATE; 
newwin. FirstGadget = NULL; 
newwin.CheckMark = NULL; 
newwin.rttle = (UBYTE •) "LittleDraw"; 
newwin.Screen = LDraw^scr; 
newwin.BilMap = LDraw_bltm; 
newwlaMlnHeight = MINHEIGHT; 
newwln.MInWidth = lutlNWIDTH; 
newwIn.MaxHelght = HEIGHT; 
newwIn.MaxWIdth = WIDTH; 
newwtn.Type = CUSTOMSCREEN; 
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II ((LDraw_win = (struct Window *) Open- 
Windowf&newwin)) ==NULL) 

( 

/* and so on */ 

) 



r AmeegaVlew version '/ 

SCREEN LDraw scr; 
WINDOW LDraw win; 



amigavlew open(); I" Init AmeegaVlew, open 
Amiga libraries */ 

/■ Open screen, allocate Bitmaps, similar to 
Intuition */ 
/* then... */ 

LDraw_wln = window^create (LDraw_scr, 

0, 0, WIDTH, HEIGHT, 

WiNDOWJnput, MOUSEBUTTONS | 

CLOSEWINDOW I 

GADGETUP 1 MENUPICK, 
WINDOW_SpeclalFealLre, BORDER- 
LESS I ACTIVATE, 

I' It figures out SuperBllMap '/ 

WiNDOW_SyslemGadgef, WINDOWDEPTH 
I WINDOWCLOSE, 
WlNDOW^TIile, •■ Little Draw", 
WINDOW_BilMap, LDraw_^bltm, 
WINDOW_MlnWidth, MiNWIDTH, 
WINDOW_MinHelglH, Ml NH EIGHT, 

0); 
/■ end the argument list */ 

If (LDraw_win =s NULL) 

{ 

r errors V 

J 

What AmeegaView does here is 

replace the process of filling in a long 
C struct and then calling an Intuition 
function with the simpler process of 
calling a corresponding AmeegaView 
function with a few fixed and a num- 
ber of optional arguments. The ivin- 
dow_create() function, for example, 
requires a SCREEN argument and the 
left/top/width/height components of 
a window. It fills in default values for 
the other arguments if you don't spec- 
ify them. In the example above, I 
chose to fill in a few other slots with 
nondefault values, to tell Ameega- 
View which input events, special 
features, and system gadgets I wanted 
on the window. These optional argu- 



ments are listed in keyword-value 
pairs, as with WINDOW_MinWidth, 
MINWIDTH. These pairs can appear 
in any order in the list after the re- 
quired arguments; the final argu- 
ment ends the list. I found this format 
easy to use — not much different from 
setting up a long printf. With 
AmeegaView filling in defaults for 
things I normally copied in from oth- 
er, earlier programs, I cut down on 
source size. The expense, of course, 
was in executable size: The Ameega- 
View functions added 1.0-12K to a 
small program, more to a larger pro- 
gram using more of the library. 

Windows and screens are a little 
easier with AmeegaView, yet not 
extremely so. But AmeegaView goes 
on to make menu-building, event- and 
gadget-handling, drawing, and IFF 
pictures easier, too. For example, the 
Intuition event-loop process is much 
simpler, from: 

/* intuition style '! 

struct intulMessage 'msg; 
ULONG msgclass; 
USHORT msgcode; 
struct Window 'win; 

for(;;) 
( 

if ((msg = (struct IntulMessage ") 
GetMsg(win->UserPort)) == NULL) 



{ 



Wart(1 « win->UserPort->mp_SiaBlt); 
continue; 



} 



msgclass = m5g->Class; 
msgcode = msg->Code; 
HeplyMsg (msg); 
switch (msgclass) 
( 
/•...•/ 

} 
) r end for */ 

to: 

r AmeegaView style */ 

EVENT anEvent; 

WINDOW win; 

/*...•/ 

input Jnsert(wln); /• Let AmeegaView know to 

watch for '/ 

/* events from win */ 

for(;;) 

( 

anEvent = Input_rBadO; 



if (anEvent == NULL) 

continue; 
switch (evenl_cias5(anEvent)) 

{ 

/*...'/ 

} 

} 

Again, the AmeegaView version is 
not trivial, but is much simpler than 
the Intuition version. And I can still 
get all the information out of the Mes- 
sage/Event that I want — the message 
class, gadget or menu ID, and so on. 
AmeegaView provides simplified 
functions for the following kinds of 
Intuition objects: Screen, Window, 
Menu, Gadget, Image, Border, IText, 
Requester, and IntutMessage. Other 
Amiga graphical objects supported 
include RastPort, Font, BitMap, Layer, 
multi-segment lines, and bitmap and 
color data associated with images. To 
use them, your program must include 
Ami ga View/a miga vie w.h, link with 
the SAS/C or Aztec C library, and 
provide a C routine called clean_up() 
with no arguments, for exit process- 
ing. It also must call amigaview_ 
openO before calling any other 
AmeegaView routines. After that, it 
can open screens and windows; build 
and modify menus, lists of gadgets, 
and requesters; and draw to its heart's 
content. 

One of these objects is a very handy 
combination of several gadget fea- 
tures. A CHOICEGROUP uses a list of 
gadgets with mutual exclusion to 
provide similar functionality to Radio- 
Buttons for MicroSoft-Windows and 
the Macintosh. In such a group of 
gadgets, only one gadget can be "on" 
(selected) at a time; the user can click 
on an unselected gadget, tunung it on 
and automatically turning off the 
previously selected one. These are 
handy for implementing "pick one of 
these" requestors. 

I had some problems with the docu- 
mentation. It was apparently written 
by a programmer and not very well 
organized. Most of the information I 
wanted v\'as there, but it was full of 
distracting typos. Most of the routines 
are reasonably named; all WINDOW 
routines begin with window^, for 
example, but event routines began 
with event_, inputs and even multi- 
inputO (although the docs said this 
one is obsolete). Capitalization is not 
consistent; for example, there is 

Continued on p. 60 
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<y An Introduction 

To Boopsi 

The author of 2.0' s object-oriented 
Intuition programming language helps get you started. 

By Jim Mackraz 



PROGRAMMING A NICE user interface under Intuition 
in the conventional way is more difficult and frustrating than 
it should be. If you are already familiar with Intuition, you'll 
find relief in OS 2.0's object-oriented programming support. 
The goal of the Basic Object-Oriented Programming System 
for Intuition (Boopsi) is to make things at once easier, more 
powerful, and more standardized. Boopsi is ver)' helpful for 
writing 2.0 "new look" applications, especially in dealing dy- 
namically with various font sizes and screen resolutions. 

Before we jump into creating all sorts of new and inter- 
connected custom gadget objects, we will start by using some 
of the ready-to-use classes of objects that are implemented in 
Intuition. Most of the important concepts of object-oriented 
programming will show themselves as we explore these sim- 
ple examples, so if you're familiar with object-oriented pro- 
gramming, you will catch on quickly. (For a more technical 
discussion of Boopsi, see the 1990 Commodore-Amiga De- 
veloper Conference notes.) 

ROUGH SPOTS IN INTUITION 

First, a little stage setting is in order, We on the design 
team have learned a lot about Intuition's strengths and weak- 
nesses in the last several years. Here are some fundamental 
areas of version 1.3 and earlier that we identified as needing 
attention: 

• Intuition has proven to be at once too open and too re- 
strictive. A button can be represented by any Intuition image, 
but nobody specifies or provides the best image to use. At the 
same time, the possibilities with Intuition images are rather 
limited. To see a standard look in applications, some standard 
and well-designed images have to be made easily available 
to applications. 

• Constructing user interfaces from pieces is sometimes dif- 
ficult. It's hard to encapsulate all the components of a scrolling 
list, for example, so that you can throw together a scrolling list 
and two command buttons in a requester and move on to the 
important part of the project: deciding how a scrolling list 
and a couple of buttons can bring benefit to the user. 

• Intuition support is at a very low level; only the struc- 
tures and constants are defined for the primitive image and 
gadget constructs. No routines are provided to dynamically 
allocate and initialize these nor to convert the data structure 
fields (such as VertPot and HorizBody) to meaningful quan- 
tities. Procedural wrappers around gadgets and images have 
to be provided by the applications progranuner — each ap- 
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plications programmer. 

• More problems crop up when you try to implement a re- 
fined look to all the gadgets and images. The primitive types 
provided are not sufficient, and you cannot mix text, line 
drawings (borders), and raster images in a linked drawing 
list. To create a button with a label centered in a filled-in 
beveled box, you must provide the text in one place, convert 
your algorithm for drawing beveled boxes into the proper- 
size image raster, and provide that raster in a separate place. 

• Perhaps the biggest problem with Intuition is that it is not 
extensible. Every mechanical improvement in gadget func- 
tionality has to be implemented in ROM (or by complete re- 
placement of the gadget mechanism). If programmers can be 
trusted to exercise good judgement and restraint with re- 
gards to standards, then providing programmers with means 
to specialize and extend the types of objects implemented in 
ROM allows us to reach a much greater level of refinement 
in how programs look and how they interact with the user. 

BOOPSI COMES TO THE PARTY 

On other computer platforms, object-oriented program- 
ming has proven itself suitable, almost ideal, for addressing 
these kinds of problems in graphical user interface systems. 
User-interface data structures are represented as objects with 
a uniform procedural interface, often called semimg a message 
to an object. An object is not just a data structure, similar to a 
window, gadget, requester, or image, but also a handle on the 
executable subroutines that operate on the data and define 
the object's behavior. A class refers to support for objects of 
some specific type. If you wanted phone-number gadgets, 
you would implement the phone-number gadget class, and 
in your programs create from that class and use some phone- 
number gadget objects. 

Boopsi is an attempt to bring some object-oriented pro- 
gramming to the Amiga, especially to Intuition program- 
ming. It shares principles with most other object-oriented 
programming systems, but I placed some unusual require- 
ments on it, including: 

• You should be able to use any programming language 
to write programs using Boopsi and predefined classes. If 
the programming language is sufficient to implement an 
Amiga interrupt handler, then you should also be able to im- 
plement new Boopsi classes. 

• Boopsi must be small to fit in ROM, minimize its use of 



RAM at runtime, and be reasonably fast on modest hardware. 
Remember, the core of the Amiga product line is the A500. 

• The user-interface classes must be compatible and inte- 
grated with existing Intuition concepts. Boopsi has to fit into 
the rest of Intuition, not hang off the side. Support for the 2.0 
new look was the project's highest priority. 

• Applications and classes implemented for them have to 
be protected against future changes to the implementation of 
system classes. I could not expect every Amiga appUcation 
using Boopsi classes to be recompiled because somebody at 
Commodore needed to add separate line-width and line- 
height parameters in the embossed-box image object data 
structure. 

To abide by these rules, we had to accept that Boopsi was 
not going to be the be-all, end-all object-oriented application 
development environment. We decided if it satisfied these re- 
quirements and helped solve some of Intuition's problems, 
it would be worthwhile. It has already proven of great value 
in implementing the new look of 2.0 system gadgets, glyphs, 
and requesters. 

CREATING BOOPSI OBJECTS 

All of the benefits in the world are not going to matter if 
Boopsi is just too difficult to use. Let's take a look at Listing 
1 and see how it stacks up. This code fragment creates an em- 
bossed box image, draws it into a window, and then dis- 
cards it. 

Listing 1: 

struct Image 'boximage; 

boximage = (struct Image *) NewObJecl( NULL, "frameiclass", 
IA_Wldtti, 60, 
lA^Height, 40, 
TAG_END ); 

Drawlfnage( w->RPort, boximage, 20, 40 ); 

DlsposeObiecl( boximage ); 

The first of the three program statements creates an image 
structure using the Boopsi function NewObject(). (Like al- 
most all of the Boopsi functions, NewObject( ) is a function in 
intuition.library.) To create an object, you identify the class 
of object you want. Here, it is specified by the string frame 
iciass, which is an abbreviation of frame image class. This 




Rgure V An enlarged view ol a sample BeopsI requester, 

class is public, in that it is available for any application's use 
and is referenced by its name. When you advance to imple- 
menting your own classes, you should start with private 
classes that only your application can use. Such private class- 
es are identified by a pointer. Here, we pass NULL for the 
pointer because the class is public. The class we are using cre- 
ates objects that behave like images. In traditional object-ori- 
ented programming fashion, frameiclass is a subclass of the 
base image class. It is said that frameiclass inherits behavior 
from imageclass. 

The next several function arguments to NewObjectO are at- 
tribute tag-value pairs. The symbols lA Width and IA_Height 
are defined (in the include file intuition/ imageclass.h) to con- 
stant values that identify (tag) the image width and height at- 
tributes. The IA_ prefix in the symbols stands for Image At- 
tribute. Following each attribute tag is the attribute value, 
here some arbitrary numbers to specify the image width and 
height. You can specify as many attribute tag-item pairs as 
you want to NewObjectO; you indicate the end of the list 
with the special tag value TAG_END. 

Passing attribute lists like this in a function call with a vari- 
able number of arguments is actually just a device of the C lan- 
guage. The formal system interface behind NewObjectO 
passes the address of an array of Tagltem structures, which 
NewObjectO just assembles on the stack. You can pass ar- 
rays, too, and even mix and match variable argument lists 
with fixed arrays. (See the documentation and include files for 
the new 2.0 utility. library for general information on using at- 
tribute tag lists, which pervade the new programmer inter- 
faces throughout 2.0.) 

You can use the function NewObjectO to create all Boopsi 
objects, not only images. In general, an object is represented by 
an absh-act pointer. Exactly what it pomts to is often private in- 
formation. Ideally, all specification and access of object pa- 
rameters would be done via attribute tags and values passed 
to functions NewObjectO, SetAttrsO, GetAttrsO, and their 
equivalents. That would be obeying a true black-box interface. 

As part of the charter of compatibility and making things 
fast and small, however, there are some exceptions. In par- 
ticular, for image and gadget classes the function NewOb- 
jectO returns a pointer to a familiar Intuition Image structure 
or Gadget structure, respectively. 

You should severely Umit your interpretations of the data 
fields in these transparent object struchires, preferably just to »- 
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position and dimension fields for images and gadgets, and 
the Nextlmage field for images. When available, always use 
the formal attribute mechanisms for changing any data struc- 
ture field; do not poke the objects. 

USING AND DISPOSING OF IMAGE OBJECTS 

Moving on to the second program statement in Listing 1, 
we see another compatibility trick. You can pass image and 
gadget objects to the Intuition functions that accept images 
and gadgets, respectively, as parameters. The function Draw- 
ImageO historically has rendered bitmap raster images using 
the Blitter. Here, however, Intuition detects that the image 
passed is a Boopsi image object and relies instead on the ob- 
ject's class implementation to perform the desired action: 
Draw an embossed box. 

As you will see a littie later, every action on objects, in- 
cluding draw, is accessed through a common interface func- 
tion named DoMethod( ), which is Boopsi's version of sending 
a message to an object. DrawlmageO just 
calls DoMethodO for Boopsi images. (The 
second example calls DoMethodO directiy, 
to illustrate the equivalence.) 

The most interesting part of object-orient- 
ed programming is probably apparent al- 
ready. We do not know how the embossed 
box is rendered or even how it is represent- 
ed internally. There's a subroutine some- 
where that does the right thing, and our only 
path to that subroutine is through the object. 
If we had an image class whose objects rep- 
resented pictures of the phases of the moon, 
we might have even less idea how it really 
works, but we could call the exact same 
function, Dra wImageC ), to get the desired re- 
sults. The point is that all we want to do is 
draw the thing, not be bothered with the de- 
tails. Nor do we want to carefully call some DrawMoon( ) func- 
tion when dealing with MoonPhase images. 

Applying the same operation to objects of a variety of class- 
es, and getting the results appropriate for each type of objects, 
is called polymorphism in the object-oriented programming 
world. This is where the power lies. 

If you've ever been deeply troubled by the fact that Intu- 
ition Image, Border, and IntuiText structures each have their 
ovm rendering function (DrawlmageO, DrawBorder( ), and 
PrintlTextO, respectively), are not self-identifying, and can- 
not be intermingled in a linked list, then rejoice: You are al- 
ready an object-oriented programmer, and Boopsi puts an 
end to this kind of nonsense once and for all. 

The third and last statement in Listing 1 also demonstrates 
polymorphism. The function DisposeObjectO deallocates 
every object returned from NewObjectO, regardless of its dass. 
This' can help out certain schemes of resource hracking and 
cleanup; it is also convenient tliat you can pass a NULL pointer 
safely to DisposeObjectO (and, more generally, to DoMethodO). 

NEW-LOOK BUTTONS AND THEIR IMAGES 

The 2.0 Amiga user-interface new look makes heavy use of 
embossed frames and silkscreened button glyphs. It is com- 
mon that a frame must be calculated to enclose some centered 
image contents. Also, the colors used to draw system gadgets 
depend on the screen they appear in. To handle these and 
other new-look requirements, there Is a bundle of useful in- 



formation associated v^ith each screen that the fancier im- 
ages use to determine their dimensions and colors. The in- 
formation is contained in the Drawlnfo structure. 

Listing 2 uses a scre^en's Drawlnfo structure to render a 
"smart" image object. 

Listing 2: 

Struct Drawlnfo 'drinfo; 
struct ImpDraw drawjHirams; 

drinfo = GetScreenDrawlnfo( window->WScreen ); 

f a new generalization of DrawlmageO *' 
DrawlmageState( w->flPort, txixlmage, 20, 40, IDS_SELECTED, 
drinfo ); 

/* Same function wilhoui: the wrapper, using stack-based 
arguments. 
7 

offs«t|>alr = (20 « 16) | (40); r mai^e a ULONG '/ 
DoMelhod( boximage, IMPDRAW, w->RPon, 
offsielpair, IDS_SELECTED, drinfo ); 

f San-ie again, using DM() the packaged- 
parameter version of DoMethodO 
*/ 

draw_params.MethodlD = iM_DRAW; 
r identities this struct '/ 
draw_params.imp_RPon = w->RPort; 
draw_params.lmp_Offset.X = 20; 
r X and Y are WORDS •/ 
draw_params.imp_Otfset.Y = 40; 
draw_params.imp„State = IDS_NORMAL; 
<lraw_params.imp_Drawlnfo = drinfo; 
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DM( boximage, &drawj3arams ); 

Generalizing the existing function DrawlmageO, a new 
function DrawImageStateO has been introduced. This ex- 
tends DrawlmageO to provide a pointer to the useful Draw- 
Info structure and to specify which state you want your im- 
age to render, such as the selected state of a gadget button. 
Putting this knowledge in the images lets you fine-tune how 
gadgets should look in action, without needing to deal with 
more than one image per gadget. 

Listing 2 also demcnstrates tvvo equivalent invocations of 
DrawImageStateO. Like DrawlmageO, DrawImageState( ) is 
also just a wrapper ciround the ubiquitous dispatcher Do- 
MethodO. The example shows both a stack-based argument 
interface to DoMethodO and an alternative packaging of the 
parameters in a sh-ucture defined in intuition/imageclass.h. 
The parameters to DoMethod( ) depend on which operation 
or method function you are invoking. The method ID used for 
DrawImageStateO and DrawlmageO is IM_DRAW. This 
method ID dictates which operation the object will perform. 
The object's class inspects this ID and dispatches to the ap- 
propriate software. 

FRAMES AND CONTENTS 

Consider putting a text label inside an embossed box. How 
big do you make th€i box, and how do you center the text? 
Only when the intelligence behind the frame is coupled with 
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the data in the Drawlnfo structure can a perfect answer be de- 
termined. The font of the text is clearly important, but so is 
the "shape" and thickness of the frame. Ideally, the resolu- 
tion of the screen's display mode should play a role in de- 
termining the thickness. 

The accompanying example programs (in the Mackraz 
drawer on the companion disk) demonstrate a few different 
ways you can compose image frames with their contents to 
get the results you want. Centering text or pictures in em- 
bossed frames is only one part of the general layout problem, 
but it is enough to see the basic sequence of operations. 

First, you have to rely on the intelligence of the framing 
object to tell you how big to make the frame for the contents 
to fit. Subsequently, you might want to add a little more 
space for aesthetics or to shrink or constrain the contents, if 
that size frame is too big to fit in the available screen space. 
Once you work out how big you want the frame to be, you 
can then rely on the frame-image object to tell you how best 
to center the contents within the chosen 
dimensions. 

As far as your interactions with the 
frame are concerned, there are two steps: 
query the frame for its recommended di- 
mensions and, after consideration or ad- 
justment, specify to the frame which di- 
mensions you want to use, and let it 
adjust (center) things appropriately. Both 
of these operations are invoked by a call 
to DoMethodO for the IM^FRAME 
method — this is the first method we have 
dicussed without a familiar wrapper 
function. Again, the parameters you pass 
to DoMethodO for 1M_FRAME are de- 
fined by a structure in intuition/image- 
class.h. One of the parameters deter- 
mines whether you are inquiring about a 
recommended frame dimension or specifying the dimen- 
sions you decided on. 

A NEW-LOOK REQUESTER 

Now we'll discuss the more interesting of the demo ex- 
amples (boopsi_request.c), which creates a new-look-style 
requester with a proportional (slider) gadget in it. It is a "per- 
centage requester" and prompts the user to use the slider to 
specify some percentage between and 100, inclusive (see 
Figure 1 ). System requesters do not have sliders in them, so 
tliis is a fine example of extending the system by piecing to- 
gether objects from predefined Boopsi classes. 

In truth, the example really does not use a requester, but 
puts up the equivalent visuals in an Intuition window. For 
illustration, the program opens this window on the default 
public screen and uses the new Intuition functions LockPub- 
Screen( ) and GetScreenData( ) to lay out the request window 
before opening it. It is still impossible to get a 100% reliable 
prediction of what the border dimensions of the window will 
be when it opens, but the program uses new 2.0 techniques 
to specify the inner dimensions and lets Intuition worry about 
the border thicknesses. 

Tlie system requesters, Uke our example, have a handful of 
button gadgets, and ours also has a proportional gadget to 
specify percentage. The buttons each have an embossed 
frame, but the program shares a single frame-image object be- 
tween all buttons. The text labels in the buttons are also low- 
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overhead in that no IntuiText structures are involved, just 
plain ASCII strings. 

In addition to the frame image shared by the buttons, there 
are a few other image objects, including a special object to dis- 
guise the requester IntuiText as an image, a frame for the text 
and the slider, and an image object that renders a stipple fill 
pattern within the window interior. These images are all 
chained together and attached to an invisible surrogate gad- 
get so that it is easy to position them together within the win- 
dow borders and Intuition automatically updates all of the 
artwork whenever it refreshes the window gadgets. 

BOOPSI SLIDERS 

Boopsi_request.c uses Boopsi classes to create the requester 
gadgets as Boopsi objects. The button gadgets are quite spe- 
cialized and are designed for the new look. They are partic- 
ularly smart about placing a simple text label within the 
raised embossed border. 

The proportional gadget is also created 
as a Boopsi object, and what would any 
repackaging of proportional gadgets be 
worth if we did not finally dispense with 
the incredibly difficult programmer inter- 
face to the "Pot" and "Body" values of 
proportional gadgets? 

As we learned at the begirming, the inter- 
face to data object values is best handled by ■ 
using attribute tags. Three new attribute tags 
are defined for propgadclass: PGA_ 
Top, PGA_Visible, and PGA„Total. These 
names come from the common use of pro- 
portional gadgets as scroll bars. For that use, 
if you had 100 lines of text to display in a 25- 
line region, you would specify PGA_Total to 
be 1 00 and PG A_Visible to be 25. You would 
use the attribute PGA_Top both to specify 
and inquire the "top line" displayed. When displaying the first 
25 lines of information, PGA_Top would be zero. At the other 
extreme, the top line of the last page of display would be 75. In 
a future article, I will show how you can arrange to receive ID- 
CMP messages for slider dragging only when the value of 
PGA_Top changes, which is just what you want. 

In our example at hand, we don't want a scroll bar, but a 
valuator that takes values from to 100 and increments or 
decrements by one for each container cUck. We do this by 
specifying PGA_Total to be 101 (0 to 100 inclusive) and 
PGA^Visibletobel. 

WHEN DO WE START? 

As with all of the new features of 2.0, it's a little difficult to 
know just when you can use Boopsi in new software prod- 
ucts and have a sizable installed base of 2.0 operating systems 
out there to run them. While you wait, you might want to use 
Boopsi in non-product research projects as practice. When 2.0 
ships to the mass market, I anticipate Boopsi will be one force 
behind an explosion of new and revised applications that 
share the attractive new look and have a new high level of 
user-interaction refinement. ■ 

Jim Mackraz is a cotisidtant ami sofiimre developer living in Pah 
Alio, CA. He ivas responsible for Intuition for five \/ears. Write to 
hint cjo The AmigaWorld Tech Journal, 80 Elm St., Peterbor- 
ough, NH 03458, or contact him on BIX (jmackraz). 
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System Events and 
Event-Handling Routines 



Find out who does what to whom. 



By Eugene Mortimore 



THE AMIGA'S COMPLEX multitasking software system 
can appear intimidating to even experienced programmers. 
One of the reasons for this apparent complexity is that many 
extremely vital routines were preprogrammed into the sys- 
tem, thereby saving you much work. Among these are the hid- 
den hardware-interrupt routines that allow programs to in- 
teract with and respond to real-time outside events. While 
always hidden from your direct view, the globally present 
Exec-system internal routines maintain order in a system 
where outside real-time random events, intertask task-syn- 
chronized nonrandom events, and the machinestate transi- 
tions they bring about occur in split microseconds. To main- 
tain order among all routines (system-predefined and 
programmer-defined) that need to share data, memory, CPU 
time, and other sometimes scarce system resources, the Ami- 
ga software system has a number of bookkeeping mechanisms. 

As your programs become more complex, you may won- 
der: When is my task routine active? How did it become ac- 
tive? What is my task routine doing now? When are other 
task routines in the system active? Why do they become ac- 
tive when they do? How can I design my task to expedite its 
execution? What system- wide information can my task rou- 
tine access? To answer these questions, this article will focus 
on the functional purpose and behavior of the most prevalent 
Amiga routine types. I will also try to make the descriptive 
language and the general interactions of Amiga processes, 
tasks, interrupts, and traps — and their associated routines — 
more precise, to help you place the tasks and routines you de- 
fine in the appropriate total system context and understand 
the general logic of Amiga multitasking system operations. 

Part of this article is concerned with software-interrupt 
events and their associated software-interrupt routines. Exe- 
cution of these interrupt routines can be initiated by the Exec 
Cause function or through the use of software signals and 
their associated Exec message ports. Although I confined this 
article to the Exec Cause function mechanism for inducing 
software-interrupt events, it still illustrates the essential pur- 
pose and features of this type of interrupt routine without the 
added complexity required to discuss software signals. 

THE EXECBASE STRUCTURE'S IMPORTANCE 

Key to our discussion is the ExecBase structure, the pri- 
mary bookkeeping mechanism for all concurrent tasks in the 
Exec software system. The Exec system-internal routines con- 
tinuously maintain and update its parameters as task switch- 
ing proceeds. This maintenance and updating — the continu- 
ous writing of some of its parameters — occurs on a very tight 
time scale. (While I will discuss only ExecBase structure pa- 
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rameters that relate to this article, you can find the complete 
definition in the execbase.h include file.) 

Any task can look at (read) the ExecBase structure's pa- 
rameters at any time to get a system- wide snapshot of the sys- 
tem's most vital cha]-acteristics. For example, the ExecBase 
structure TaskReady List substructure contains a system- 
wide list of all tasks currently ready to run in the system. 
Your task can examine the task names in that list (the list 
Node structure ln_Name parameter) to determine which 
tasks are currently ready to execute. 

In a similar way, the TaskWait List substructure contains 
a system-wide list of all tasks currently waiting to run in the 
system. These tasks are usually waiting for a software signal. 
Your task can examine the task names in that list (again the 
list Node structure l.n_Name parameter) to determine all 
tasks that are currently waiting to execute, 

ExecBase's ThisTask parameter holds a pointer to the Task 
structure of the currently executing task. Also, its TaskExit- 
Code parameter always contains a pointer to the exit code for 
the currently executing task. This exit-code routine could be 
designed specifically for the task — and referenced in a par- 
ent-task AddTask function call that created the task — or it 
could be the system's default task-exit code. 

The TaskTrapCodf! parameter houses a pointer to the en- 
try point of the current task's currently executing trap rou- 
tine. This trap-code routine could be designed specifically 
for the task and have a trap number referenced in a task-re- 
lated AllocTrap funcfion call. 

The IntVects[16] parameter always contains a group of 16 
IntVector substructures defining the current system-wide 
hardware-interrupt routines. These IntVector structures de^ 
fine how all keyboard interrupts, vertical-blanking interrupts, 
and so on are currently treated. 

Each IntVector structure contains a pointer to the code 
(iv_Code) and the data (iv Data) of the currently effective 
hardware-interrupt ::outine assigned to a piece of Amiga 
hardware. These IntVector structures define the current hard- 
ware-interrupt routines that are used throughout the system. 
Upon system startup, most of these routines and their data 
are in ROM. When a specific task calls the Exec library Set- 
In tVector and AddlrtServer functions to replace or extend 
these hardware-interrupt routines, however, those newly- 
defined routines become effective throughout the system and 
will be used by all processes, devices, and tasks currently in 
the system. For this reason, make hardware-interrupt routine 
modifications and amendments with great care and keep an 
eye to their impact on other concurrent tasks in the system. 

The five List substractures in the ExecBase structure's Soft-» 
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VIDEO TOASTER 



The Video Toaster™ from NewTek is hailed as the world's first video 
computer card enabling broadcast-quality production on desktop! TheVIDEO 
TOASTER" videotape is indispensable for Amiga owners considering the 
purchase of a Toaster" or those curious about all the excitement over this 
"revolutionary breakthrough in technology." 

VIDEO TOASTER" provides in-depth, comprehensive information on the 
Toaster's" wide array of features and amazing capabilities. Topics covered 
include installing the Toaster'" in the Amiga 2(X)0; adding and testing other 
essential equipment; selecting source material; and manipulation of the many 
digital video effects, including flips, tumbles, mirrors, spins, splits and titles. 
This video also illustrates how to generate and then superimpose letters over 
pictures, how lo produce three-dimensional animations and how to paint on 
video images. 

See for yourself what the excitement is all about! 



HOTROD! 



HOT ROD YOUR AMIGA provides authoritative advice on how to achieve 
maximum power with your machine, whether you own a series 500, 2000 or 
3000 Amiga. 

HOT ROD YOUR AMIGA teaches you how to expand memory internally 
and externally. U provides valuable, in-depth information on selecting and 
installing hard drives, memory boards and accelerators; back-up software and 
utilities; RAM and drive .space differences; and other "hot-rodding" tips. It also 
covers high-end peripherals such as DCTV" and the revolutionary Video 
Toaster"". Don't wait to soup up your Amiga! 



PRIMER 



THE AMIGA PRIMER video provides step-by-stcp instructions covering the 
many features of the Amiga. Whether you're a new owner or an experienced 
user, this easy-to-follow video will prove invaluable. Packed with almost 90 
minutes of detailed information, THE AMIGA PRIMER teaches you in an 
entertaining format with vibrant graphics and upbeat music. 

Gain the full benefits that the Amiga has to offer on all Amiga models. 
System 2.0 and Amiga Vision^. It also covers the Amiga workbench, the CLI, 
peripherals and utilities. There's no easier way to master your Amiga! 
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Intsl5] parameter define the software-interrupt routine queues 
of currently pending software-interrupt routines. The Exec 
system assures that software-interrupt routines always exe- 
cute ata higher priority than tasks, but at a lower priority than 
hardware-interrupt routines. One use for software-interrupt 
routines is to modularize your tasks into micro tasks that ex- 
ecute on the side and do not require explicit task bookkeep- 
ing — no Task structure. Another is to allow any extensive- 
hardware-interrupt-related processing to be deferred until all 
currently pending hardware-interrupts are completed. 

Finally, the ExecBase structure Quantum parameter is di- 
rectly related to the time-slice round-robin time-quantum pe- 
riod allowed for each task to execute when round-robin mul- 
titasking is occurring. From now on, I will use the term 
Quantum to refer to the actual number of seconds between 
task switches. At present, the system sets Quantum to 16 in 
version 1.3 of the operating system, and to 4 in OS 2.0. While 
Quantum is a small time integral, it is a sufficiently long pe- 
riod for a large number of task (68000 assembly-language) in- 
structions to execute before task switching reoccurs. 

SYSTEM-CREATED TASKS VS. PROGRAMMER- 
DEFINED TASKS 

As a programmer, you will spend most of your time pro- 
gramming and debugging your own programmer-defined 
tasks. As discussed above, in the most common circumstance, 
these program-process tasks will be automatically created by 
the system software whenever it creates an AmigaDOS pro- 
cess associated with your program. The Exec and Amiga- 
DOS system software automatically work together to create 
a program-process task when your program is launched from 
the CLl or Workbench. At that time, the system software will, 
in essence, allocate and initialize a Process structure and its 
associated Task structure, automatically setting appropriate 
structure parameters to allow the system software to main- 
tain the bookkeeping on your task. 

While most of the time the system software handles task 
bookkeeping, occasionally you might create a task inside 
your program source code by allocating and initializing a 
Task structure and, in effect, simulating the system software's 
setup duties. In either case, it is helpful to know how your 
tasks fit into the total scheme of things: what your task-re- 
lated programming responsibilities are, what the system does 
for you, and how the system behaves when your task exe- 
cutes and interacts with other tasks and other task routines 
concurrently in the system. The best approach to under- 
standing these task-to-task interactions is to focus on the gen- 
eral sequence of system events and study the behavior of 
task and other routines that execute during that sequence. 
This way you will begin to fathom the functional nature of 
the various routine types and then be able to focus on the sys- 
tem's flow of control and relate it to your known program- 
ming requirements and the fixed constraints in the system. 

To this end, let's take a look at the general flow of execu- 
tion among programmer-defined-task and other task-related 
routines in our multitasking system. If you concentrate on the 
main principles highHghted here, you wUl better understand 
general Amiga programing principles and the specific se- 
quence of task-related events, as tasks are continuously 
switched in and out of execution on a very-tight time scale. 
Your new understanding in turn will give you a better grasp 
of the context in which you program and in which your soft- 
ware executes. This will help you avoid competing with or 



duplicating the respcmsibilities and actions of the Exec or 
AmigaDOS system internal routines, letting you take full ad- 
vantage of what the sj'stem can do for you. You can use these 
insights to better understand the interactions among your 
program-defined task routines and both system-predefined 
and programmer-defined task routines that are concurrent- 
ly executing in the system. 

THE GENERAL SEQ UENCE OF TASK - 
EXECUTION EVENTS 

We will focus on tlie interaction of programmer-defined 
task routines, predefined hardware-interrupt routines, pro- 
grammer-defined hardware-interrupt routines, programmer- 
defined software-interrupt routines, programmer-defined 
software- and hardware- (68000 processor) trap routines, and 
the system internal routines. These categories cover all the 
types of routines you will need to consider. While there may 
be other mechanisms for creating and then initiating execu- 
tion of these routines — for, example, software signals — these 
are the only routine types understood by the Amiga multi- 
tasking system. Because Amiga multitasking is a complex 
subject, it is very useful to look at simplified situation that de- 
picts the most important routine scheduling mechanisms. 

Figure 1 illustrates two tasks and shows how the multi- 
tasking system works. Each could be a short graphics task, 
either a standalone task or an AmigaCXDS process task, that 
draws figures in an Intuifion window by calling Graphics li- 
brary functions. Notice that I arbitrarily divided each task's 
code into four blocks. You could create these tasks either as 
explicit tasks within another program (spawn them as child 
tasks) or as separate program-process tasks whose simulta- 
neous execufion is somehow started from a CLI window or 
a Workbench icon. 

The first block of code contains task inifialization state- 
ments and is where you open libraries the task requires and 
allocate and irutialize: the dynamic structures the task uses. 
For a graphics task in an Intuition window, you would open 
the Graphics and Intuifion libraries and allocate and initial- 
ize Screen, Window, and perhaps Rastport structures here. 

The second and third blocks are for code that accomplish- 
es operations specific to the task. For a graphics task, this 
would include calls to the Graphics library funcfions that 
draw graphics in your newly opened Intuition window. 

The fourth block houses the code to clean up your task. 
Here you would close your opened Ubraries (Graphics and 
Intuition) and free any memory blocks you allocated in oth- 
er parts — most probably the first block of your task code. If 
you modified the interrupt system, you would here restore 
the interrupts appropriately. 

Figure 1 draws attention to the relationship between the 
Exec system code, th-2 programmer-defined task code, hard- 
ware-interrupt code (system-predefined and programmer- 
defined), programmer-defined software-interrupt routine 
code, and any programmer-defined trap routine code as- 
signed to the task. The Exec system code, while not explicit- 
ly shown in the figure, is the ever-present low-level code that 
manages everything else in the system; it is the system-soft- 
ware traffic cop. As cur discussion unfolds. Figure 1 will also 
help clarify the fundional distincdon between hardware in- 
terrupts, software interrupts, and the two types of Motorola 
68000 trap events in the Amiga system. 

One of the keys to understanding the Amiga multitasking 
system is knowing tlie difference between synchronous and 



44 AugustlSqjtember 1991 



Event Handling 



asynchronous events. Tliis difference is easiest to understand 
in the context of two identical concurrent tasks. In general, if 
an event can occur at any time, it is an asynchronous event. 
If an event can occur only when a section of a task's code has 
been entered and a specific program instruction executed, it 
is a synchronous event. This distinction will become clearer 
as we discuss our two-task example in detail. 

The two large rectangles represent the executable code of 
two separate tasks. The entry and exit points (first and last 
assembly-language instructions) for the tasks are at the top 
and bottom of the rectangles, respectively. 

INTERRUPT ROUTINES AND EVENTS 

The inward-pointing arrows at the top of these two rect- 
angles depict the action of the system's elapsed-time count- 
down routine that initiates task switching every Quantum 
seconds. The diagram does not explicitly show a separate 
rectangle for the system's task-switching routine, which is the 
routine that does the actual s^vitch, changing task register 
contexts. In this discussion, it is considered to be one of the 
internal Exec system routines. You should understand, how- 
ever, that the system's task-switching routine automatically 
gets the CPU every Quantum seconds as guaranteed by one 
of the Amiga's hardware-chip-countdown registers. Once the 
countdown event occurs, the system automatically initiates 
execution of the task-switching routine and task-switcliing 



occurs. You can classify the system task-switching event as 
either an asynchronous or a synchronous event. It is asyn- 
chronous because its occurrence is not determined by the 
task code. Qn the other hand, it is synchronous because it is 
regular and predictable in timing — it does not occur at ran- 
dom times. 

The inward-pointing arrows on the outsides of the two 
task rectangles collectively represent all outside-world hard- 
ware-interrupt events that may occur randomly while the 
two task routines are executing. These arrows depict the 
source of most of the asynchronous events referred to above. 
Notice that these arrows point to random locations in the 
task code suggesting that they are induced by outside- world 
events that occur at random times dvtring the execution of 
these tasks, such as the user pressing a key. 

The four smaller rectangles in the middle of Figure 1 rep 
resent four types of additional routines. These routines may 
or may not be directly associated (assigned to the task by the 
programmer) with the two tasks. Notice that the entry and 
exit points (the first and last assembly-language instructions) 
for these four routines are at the top and bottom of their 
smaller rectangles. The inward-pointing arrows at the bottom 
of these four rectangles collectively depict all hardware-in- 
terrupt events that occur randomly while these routines are 
executing. 

Thus, there is always the possibility that a new, second • 



Figure 1: Summary of Events and Event Handling Routines 
in the Amiga System. 
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(third, fourth, or more) randomly timed hardware-interrupt 
event will occur while the interrupt routine associated with 
a previous hardware-interrupt event is executing. The Exec 
system software must be able to cope with the nested-hard- 
ware-interrupt event situation. Hardware-interrupt events 
may also interrupt software-interrupt routines, 68000 hard- 
ware trap-routines, and programmer-defined trap routines. 
(This will become clearer later.) 

FLOW OF CONTROL 

The dotted lines between aU rectangles in Figure 1 illustrate 
the flow of control in the system. When the 68000 program 
counter (address) points to the assembly-language instruc- 
tions in each of the rectangles in Figure 1, that particular rou- 
tine will be executing for a period determined by overall sys- 
tem logic and predefined system-scheduling considerations 
fixed by the Amiga's task-scheduling logic — a logic that is 
embedded in the hidden Exec scheduling routines. Specifi- 
cally, in Figure 1, you can see that each task routine is de- 
ferred (interrupted) four times to allow a task-related side 
routine to execute. The dotted lines (between rectangles) and 
the associated terminal arrow heads show that when one of 
the tasks is interrupted, execution begins at the entry point 
of these "on-the-side" routines (the top of the rectangle) and 
ends at the exit point (the bottom of the same rectangle). Con- 
trol then returns to the interrupted task at the same point that 
the task was interrupted, and its next instruction begins ex- 
ecution. Now the CPU program counter once again points to 
instructions inside the task routine itself. 

For the sake of simplicity, assume that the two tasks have 
identical code, such as two copies of the same graphics pro- 
gram launched from one Shell. In that case, each task will in- 
herit the task priority of the Shell window from which it was 
launched. For purposes of discussion, assume a task prior- 
ity; tasks will therefore execute in parallel alternately loosing 
and gaining the CPU. Under normal circumstances, every 
Motorola 68000 instruction that eventually executes in one 
task will also eventually execute in the other task before both 
truly finish execution. Except for premature task failure or 
user-task termination, this result is guaranteed by our two- 
identical task arrangement and by the way the Amiga multi- 
tasking system works. 

No matter how it is brought into existence, each task is de- 
fined by its own Task structure and has its own distinct Mo- 
torola 68000 user-mode stack specified by its Task-structure 
stack parameters. When a program process task is executed 
from the Shell or Workbench, the system internal routines 
make these initializations, On the other hand, if you spawn 
a child task within an already executing parent task, you 
must do the initializations. 

Assume that the variables taskl and task2 are defined as 
C pointers to the respecti\'e Task structures for our t^vo-iden- 
tical tasks: 

struct Task *lask1, 'tasl(2; 

The Task structure, defined in the tasks.h include file, has 
the following definition: 

struct Task ( 

struct Node (c_Node; 
UBYTE tc_FIags; 
UBYTE tc_State; 
BYTEtcJDNestCnt; 



BYTE tc_TDNe8tCnt; 
ULONG tc_SigAlloc; 
ULONG tc_SigWait; 
ULONG tc_SigRecvd; 
ULONG tc_Sig Except; 
UWORDtc_TrapAlloc; 
UWORD tc_TrapAble; 
APTR tc_ExceptData; 
APTR tc_E)(ceptCode; 
APTR tc_TrapData; 
APTR tc_TrapCode; 
APTR tc_SPReg; 
APTR tc_SPLower; 
APTR tc_SPUpper; 
VOIDtc_Switch(); 
VOID tc_Launcti(); 
struct list Ic MemEntry; 
APTR tc_UserData; 

); 

Several Task-structure parameters must be initialized be- 
fore the task is added to the system with the AddTask func- 
tion. Once the task is added, the system places it on the sys- 
tem's ExecBase struchire TaskReady list. In our example case, 
one way or the other, each of these tasks is assigned task 
priority by setting the Task structure Node substructure 
ln_Pri parameter to 0, which you do as follows: 

taskl ->tc_Node.ln_Pri = 0; task2->tc_Node.!n_Pri = 0; 

In addition, if the task uses its own trap routines, the 
tcTrapCode and tc_TrapData parameters are initialized to 
point to the programmer-defined code and data for trap 
events and the tc_SP!i^eg, tc_SPLower, and tc_SPUpper pa- 
rameters are set to specify the task stack. In our simplified ex- 
ample, this is done identically for each task using matching 
C initialization statements (with differing Task structure 
pointers, of course). 

Note that in this discussion, the Task-structure parame- 
ters, tc^ExceptCode and tc_ExceptData, used to define the 
code and data for soflware interrupts (exceptions) related to 
software signals, are not initialized because we are not con- 
sidering software signals here. We are considering only the 
Exec Cause function mechanism of inducing software inter- 
rupts. The Cause function uses the Exec Interrupt structure 
to define the code and data to handle the software-interrupt 
event. Also, specifically note that the Task structure make no 
mention of code and data for interrupt routines. We will see 
why later. 

THE DETAILED SEQUENCE OF EXECUTION EVENTS 

Each task's four cede blocks in Figure 1 (Block! through 
Block4) can also be defined by the four types of events that 
occur during task execution: 

• hardware-interrupt events and the execution of the associ- 
ated hardware-interrupt routines 

• software-interrupt events and the execution of the associ- 
ated software-interrupt routines 

• Motorola 68000 internal-hardware trap events and the ex- 
ecution of the associated hardware-trap-recovery routines 

• programmer-defini.'d software-trap events and the execu- 
tion of the associated software-trap-processing routines. 

Once the Task structure is allocated and initiaUzed for each 
task, that task is added to the system %vith the AddTask func- 
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Hon. When AddTask returns, both tasks are placed on the sys- 
tem's ExecBase structure task-ready list. Now the Exec sys- 
tem's hidden scheduler routines decide when the first task 
gets the CPU. [f, apart from the ever-present system tasks, 
these were the only two tasks in the system, the system would 
operate as follows: 
Phase One 

Because, by assumption and arrangement, each of these 
tasks has equal zero priority, the multitasking system starts 
executing one of the tasks (probably the first one added with 
a AddTask function call), and Blockl of its code begins exe- 
cution at its entry point. Quantum seconds later, Task2 begins 
execution. Tl-iese two tasks each execute for Quantum sec- 
onds—first Taskl, then Task2, then Taskl, then Task2— al- 
ternately until, by assumption, a randomly-timed hardware- 
interrupt event occurs as shown. 

Now assume Taskl was in the middle of executing a group 
of assembly-language instructions when the first hardware 
interrupt occurred. The interrupt is the outside world inter- 
acting with the task, asking for 68000 processor time to cap 
ture some information that is available only for a brief instant. 
This hardware interrupt could have come, for example, from 
someone typing at the keyboard or an AmigaDOS copy op- 
eration asking for information from the disk. The hardware- 
interrupt event couid be completely uru-elated to the task and 
therefore ignored, or it could be keyboard activity that sup- 
plies data for the task. In any case, as a result, execution of 
Taskl code ceases and the (short) hardware-interrupt routine 
associated with that particular hardware-interrupt event be- 
gins execution. 

Just prior to passing control to the interrupt routine, the 
Exec-system routines automatically save the current register 
context (DO through D7, AO through A6 and the PC and SR 
registers) for Task] on Taskl's 68000 user-mode stack. This 
is the RAM stack controlled by the Task-structure stack-defin- 
ing parameters as described above. 

The Exec system-internal routines then put the 68000 pro- 
cessor into supervisor mode and the hardware-interrupt rou- 
tine currently associated with that hardware-interrupt event 
begins execution. If it was a keyboard-interrupt event, the 
keyboard-interrupt routine places the new keystroke into the 
keyboard input buffer and very quickly returns control to the 
interrupted task. The Exec system routines then restore the 
previous task context (its saved registers) when the hard- 
ware-interrupt routine completes execution. 

If this hardware-interrupt routine is part of a linked-inter- 
rupt-server routine chain, one or more of the routines in that 
chain execute, each in turn until the hardware-interrupt event 
is fully processed. This chained-routine arrangement is use- 
ful when you want more than one thing to happen with the 
hardware-interrupt event occurs. For example, the hardware- 
interrupt associated with a math-coprocessor hardware-in- 
terrupt event has a linked-interrupt-server routine chain 
mechanism. That is, at some point in the ser\'er-routine chain, 
determined purely by the preprogrammed internal decision- 
making process in the interrupt-server routines and the 
specifics of the hardware-interrupt event, server-chain rou- 
tine execution ceases, the Exec system internal-scheduling 
routines redispatch Taskl. The Exec system routines restore 
Taskl's CPU register context from Taskl's user-mode stack 
and Taskl resumes execution where it left off. 

Here we assume no higher-priority task was added to the 
system task-ready list before the hardware-interrupt event 



occurred. This assumption virtually guarantees that Taskl 
will regain the CPU when the hardware-interrupt routine 
completes execution. 
Phase Two 

When multitasking and task-context switching resume 
Quantum seconds later, Task2 begins execution. The system 
alternately allows Taskl and Task2 to execute. The Exec-sys- 
tem internal routines automatically manage each task's stack, 
thereby saving and restoring each task's register context 
every Quantum seconds. Again, assume a randomly-timed 
external hardware-interrupt event — the same type of hard- 
ware-interrupt event as for Taskl — occurs near the middle of 
execution of Task2's Blockl code. As with the first hardware 
interrupt, the timing of this hardware-interrupt event is ran- 
dom; someone hit a keyboard key. The system saves Taskl's 
current register context and passes control to the same sys- 
tem-wide keyboard-interrupt routine used to process the first 
keyboard-interrupt event as for Taskl. Then, very quickly, 
the hardware-interrupt routine returns control to Taskl. 
Taskl begins executing again at the instruction following the 
point it was interrupted. 
Phase Three 

Quantum seconds later, multitasking again resumes; the 
system alternately allows Taskl and Taskl to execute every 
(Quantum seconds. The system automatically manages each 
task's stack, saving and restoring each task's 68000 register 
context every Quantum seconds. 

During Taskl's Blockl code execution by task-design as- 
sumption, Taskl calls the Exec library Cause function. Cause 
tells Taskl to stop executing and transfer control to one of its 
software-interrupt routines. As before, Taskl's register context 
is saved on its user-mode stack. (Note that the only argument 
in the Cause function call is a pointer to a Interrupt structure 
representing a particular software-interrupt routine.) 

Now, just as with the previous hardware-interrupt rou- 
tines, the system places the 68000 into supen'isor mode to 
process the software-interrupt routine. Any function calls 
(such as shared-library function calls) the software-interrupt 
routine makes will use the 68000 supervisor-mode stack. 
Multitasking is suspended while the software-interrupt rou- 
tine executes. 

You must understand that the task prearranges aU the ac- 
tions of softvvare interrupts that the Cause function induces 
by properly setting the parameters in an Interrupt structure 
related to the software interrupt. That is, the task initializes 
an Interrupt structure's is_Code and is_Data parameters in 
its Blockl code before calHng the Cause function in Blockl. 
Thus, the Exec Interrupt structure serves to define both the 
asynchronous, outside-world, randomly-timed hardware- 
interrupt event routines and the sychronous, task-timed, soft- 
ware-interrupt-event routines that the Cause function in- 
duces. The Interrupt structure provides a mechanism for a 
task to specify a code and data section to accomplish an ar- 
bitrary event-processing job, no matter what the source of 
that event. Also note that Cause-function-induced software 
interrupts are not defined by setting the Task structure tc_Ex- 
ceptCode and tc_ExceptData parameters; these parameters 
are used for software signal-induced software-interrupt ex- 
ception routines only. 
Phase Four 

Quantum seconds later, multitasking resumes. The instant 
Taskl regains control, it calls the Cause function and exe- 
cutes the same software-interrupt routine that Taskl previ-^- 
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ously executed. The exact timing of this second software-in- 
terrupt event is guaranteed by the assumed symmetry of the 
situation; except for using different stacks and different Task 
structures, Task! and Task2 are identical-synchronized tasks 
with one-for-one identical assembly-language instructions. 

When Task2 turns over control to the software-interrupt 
routine, the Exec system routines automatically save Taskl's 
register context on Taskl's user-mode stack, and the appro- 
priate software-interrupt routine executes in supervisor 
mode. Control quickly rehims to Task2 routines when the 
software-interrupt routine executes an assembly-language 
RTS instruction. 
Phase Five 

Quantum seconds later, multitasking resumes. Taskl now 
regains the 68000 processor. The remainder of both tasks' 
BlockZ code and part of their Blocks code executes. Once 
again, Taskl and Task2 alternately execute Quantum sec- 
onds apart. By assumption, at some point a Motorola 68000 
hardware-trap event occurs in Taskl. For example, the graph- 
ics task performs graphic-coordinate calculations that lead to 
an inadvertent zero divisor. When Taskl tries to divide by 
zero, the 68000 processor automatically senses this divide- 
overflow condition. One of the hardware trap-recovery rou- 
tines defined by the system or programmer (the one designed 
to deal with zero-divide overflow) executes. 

The trap routine should be designed to recover from the di- 
vide problem so that the Taskl can continue executing. For 
a interactive CAD graphics task, for example, this trap rou- 
tine could alert the program user to the zero-divide condition 
and ask for the user to supply new program coordinates as 
input. 

Just as with the hardware-interrupt routines, the system 
places the 68000 into supervisor mode to process the hard- 
ware trap-routine recovery code. Any function calls made in 
the trap routine use the 68000 supervisor-mode stack. Multi- 
tasking is suspended while the trap routine executes. 

The system automatically saves Taskl's register context on 
Taskl's user-mode stack before the trap routine executes. Tlie 
last 68000 assembly-language trap-routine instruction exe- 
cuted will be RTF (Return from Exception) and Taskl again 
quickly regains control. The RTE instruction places the 68000 
CPU back into 68000 user mode. 
Phase Six 

Quantum seconds later, multitasking resumes; Taskl and 
Task2 alternate every Quantum seconds. Block3 of Task2 be- 
gins execution and, by assumption of symmetry, the same 
trap problem occurs: Task2 attempts to divide by zero. The 
68(X}0 senses this divide-overflow condition and execution of 
Task2 ceases while the divide-by-zero hard ware- trap routine 
attempts to allow Task2 to recover. The trap routine finally 
executes a Motorola 68CKX) RTE instruction that rehims exe- 
cution to Task2. The RTE instruction again places the system 
back into 68000 user mode. 
Phase Seven 

Quantum seconds later, multitasking resumes; Taskl and 
Task2 alternate every Quantum seconds. Eventually, Taskl 
enters Block4 and executes a 68000 assembly-language TRAP 
#N instruction. This allows Taskl to execute an arbitrary pro- 
grammer-defined trap routine to accomplish some job out- 
side of the coding of Taskl itself— in effect, to perform a soft- 
ware-trap routine. The programmer has 16 software-trap 
routines available (16 software-trap numbers). 68000 soft- 
ware-trap routines are always initiated by the Motorola CPU 



68000 TRAP #N instruction. 

In this sense, the puipose of programmer-defined TRAP #N 
routines is very similar to software-interrupt routines except 
that their initialization mechanism is different. Software-in- 
terrupt routines are initiated by the Exec Cause function, by a 
software-exception sig;nal sent through an Exec message port 
or by some other, more direct software-signal mechanism. 

Just like a software- interrupt routine, the TRAP #N routine 
can be a large routine and is not time-critical as is a hardware- 
interrupt routine. Also like hardware- and software-inter- 
rupt routines, a trap routine executes in 68000 supervisor- 
mode, during whic'i time multitasking is temporarily 
suspended. Therefore, note that if the trap routiiie is large, the 
trap routine itself should include a call to the Exec UserState 
function, to quickly switch back to 68000 user-mode from 
within the trap routine. This keeps the essential supervisor- 
mode processing short and allows multitasking to continue. 
These trap routines provide yet another way to modularize 
your code but, because they execute in 68000 supervisor- 
mode, are most often used in the Exec system code itself. 

As before, the trap routine completely finishes execution 
and control rehirns tD Taskl. The last 68000 assembly-lan- 
guage trap routine instruction executed is RTE, and Taskl 
again quickly regains control, The RTE instruction places the 
system back into 68000 user-mode. 
Phase Eight 

Quantum seconds 1 ater, multitasking resumes and imme- 
diately, because of the guaranteed task symmetry, Task2 calls 
the same 68000 assembly-language TRAP #N routine, places 
the 68000 into supervisor-mode, temporarily suspending 
multitasking, and then completes execution and returns con- 
trol to Task2. The last 68000 assembly-language trap routine 
instruction executed virill be RTE, and Task2 again quickly re- 
gains control. The RTE instruction places the system back 
into 68000 user mode. 

Taskl and Taskl continue executing (Juantum seconds 
apart until their respective exit functions are called and con- 
trol passes back to the system. 

STILL IN THE QUEUE 

By now you should have a grasp of the four types of rou- 
tines that the Exec library funcHons can understand and man- 
age. You can see that the system's CPU is constantly svvitch- 
ing among task (and other) routines and between user and 
supervisor modes to accommodate all types of system e\'ents. 
Note that not all routines must be a direct part of an Amiga 
process or task. Inste.id, some routines can be called on the 
side as necessary. Keep this in mind as you explore ways to 
modularize your program code for maximum efficiency and 
reduce the Exec and AmigaEXDS bookkeeping overhead. 

If you study our discussion, you will begin to appreciate 
how your own program task fits into the total system, when 
that task accesses the CPU, and what considerations the Exec 
routines use to schedule tasks. To further this understanding, 
in the next issue I will expand upon this discussion's most im- 
portant concepts and examine the implications and restric- 
tions of 68000 supervisor- and user-mode execution and the 
proper use of task-related routines. ■ 

Eugene Mortimorc is a developer and t!w author of Sybcx's Ami- 
ga Programmer's Handbook, Volumes I and II. Write to him 
cjo The AmigaWorld Tech Journal, SO Eim St., Peterborough, 
NH 03458. 
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PostScript Primer 

With printer prices falling, the time is right to add precision 
graphics output capabilities to your programs. 



By Jim Fiore 



APPLICATIONS THAT DEPEND on high-quality hard- 
copy have no excuse for ignoring PostScript these days. Post- 
Script dovetails quite nicely with the Amiga's graphic 
prowess, and it is becoming affordable as the prices for entry- 
level PostScript laser printers drop, 1 intend to wipe out your 
final excuse ("1 don't know how to program in it.") by intro- 
ducing you to the fundamentals of PostScript graphics and 
adding basic PostScript output support to your applications. 

You do not need any sort of "PostScript compiler" to pro- 
gram with the language. PostScript laser printers contain Post- 
Script interpreters. In effect, when you buy the printer, you are 
also buying a miniature language-development system, the 
interpreter. (See why PostScript printers cost more than ordi- 
nary laser printers?) 

HELLO POSTSCRIPT 

A page-description language, PostScript is device inde- 
pendent. In other words, the quality of the printed page is a 
function of the mechanics of the printer, not of the PostScript 
code. This is in contrast to the Amiga's graphics library, 
which is pretty much hardwired to the Amiga's chip set. A 
good portion of the PostScript language is built around the 
needs of transferring graphics and text to paper. The balance 
of the language consists of the elements you expect in any 
high-level language, such as facilities for looping, condition- 
als, procedures, definitions, and so on. Unlike such languages 
as C, PostScript is stack-oriented and employs postfix nota- 
tion. In a statement you first place arguments onto a last-in- 
first-out stack, then give the procedure. If you had a proce- 
dure called smerzl that took two numeric arguments, a C 
language version would look like: 

smerzl( 110, 23 ); 
The PostScript scheme yields a little different statement: 

110 23 smerzl 

Like C, PostScript is fairly freeform in nature. It lets you in- 
clude blank lines and place several items on one line. The per- 
cent sign (%) denotes a comment. (Everything after % on a 
line is taken as a comment.) 

When composing a page you should keep three things 
mind: the current page, the current path, and the clipping 
path. Empty when you start, the current page is where all 
drawing takes place. You draw on the page with opaque 
paint; there is no transparency. The current path refers to a 
collection of positions, arcs, lines, and so on, and is con- 
structed using PostScript operators. This path can be very 
complex and can even cross over itself. The clipping path is 



the path that defines a printable area. For example, you might 
construct a clipping path in the shape of an ellipse. Only ele- 
ments contained within tliis ellipse will be printed; anything 
that falls outside will be ignored. By default, the clipping 
path is equal to the dimensions of the page. 

PostScript maps a piece of paper as an X-Y coordinate sys- 
tem with its origin in the lower-left comer. A positive X val- 
ue moves you to the right, while a positive Y value moves 
you up the page. Note that this orientation is somewhat dif- 
ferent than the Amiga's, which uses the upper-left as the ori- 
gin, with positive Y values moving you down the page. The 
default unit is the point, which is defined in PostScript as one 
seventy-second of an inch CAz). PostScript's operators will let 
you scale the units to your own desire, move the origin, and 
rotate the entire coordinate system. By doing so, you can 
work within your own ideal "user space." It is the job of the 
printer to map the positions onto its mechanics. This is how 
device independence is achieved. 

Let's take a look at a simple program: 

newpath 

100 200 moveto 

300 400 lineto 

stroke 

showpage 

The newpath command clears the current path and de- 
clares that you are about to start building a new one. The sec- 
ond line places the values 100 and 200 on the stack and then 
calls moveto, setting the current position. The "pen" is now 
positioned 100 points to the right of the origin and 200 points 
above it. The moveto command is functionally similar to the 
graphics library's MoveO. The program's third line draws a 
line from the current position to one 300 points to the right 
of and 400 points above the origin. Therefore, lineto is simi- 
lar to Draw(). Note that no actual drawing has taken place 
yet. The stroke command initiates the process of drawing or 
painting onto the paper. Why is this extra step required? You 
can use the moveto/Iineto commands to create a clipping 
path as well, and you may not want the clipping path to be 
outlined. The final command, showpage, indicates that all 
work on the page has been completed, and that the printer 
should create and eject it. While moveto and lineto are based 
on absolute positions, you can use rmoveto and rUneto to in- 
dicate relative positions. For example: 

100 50 rmoveto 

means move 100 points to the right and 50 points above the 
current position instead of to the right and above the origin. » 
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As you can see, the moveto and lineto operators will 
allow you to create two-dimensional graphs with ease. 
Repeated calls to moveto and lineto will create an appro- 
priate grid for the plot. Once this is completed, you can use 
a succession of linetos to connect the data to be plotted. 

COPY TO PRINT 

To see the results of the above program, the easiest method 
is to type the program into a text editor, save it, and send it 
to the printer by simply copying the file to the proper port. 
For example, if you connect via the parallel port and you call 
the program test.ps, the Shell command 

COPY test.ps PAR: 

will do the trick for you. (If you connect via the serial port, 
use SER: instead.) If you send an erroneous program to your 
printer, the device will usually just ignore it and do nothing. 
Depending on the exact error, it may eject a blank page. While 
this technique is wonderful for working out bugs in your 
code, it does not help you splice the code into your larger 
application. 

As all your program needs to do is send strings of ASCII 
text from vour program to the printer, the splicing methods 
are fairly straightforward. You could open up the appropri- 
ate DOS device (SER: or PAR:) and WriteO to it. Generally, 
opening PRT: is inappropriate, because the printer de\'ice will 
perform character translations, and you want raw character 
streams. Another possibility is to use the Exec lO routines. The 
Amiga ROM Kenml Mnnual: Libraries & Devices (Addison-Wes- 
ley) includes snippets of code that are perfect for this, includ- 
ing a "plug-in" function called PrintRaw(). (Personally, I use 
the dissidents PrintSpool library as it also takes care of back- 
ground printing. You can find it on Fred Fish disk #393.) For- 
matting the text strings is done in the normal fashion (C pro- 
grammers can use sprintfO, or roll their own). 

Shown below is a sample C program that uses the above 
PostScript code for a printer connected to the parallel port. 
For simplicity, it opens and writes to the DOS parallel device. 
The test.ps code is small enough to be placed into a single 
string. Larger applications will probably require the use of 
several strings and several calls to Write( ). 

/* simple PostScript ps.c 
For Manx 5.0, 
c p3.c 
In ps.o -Id 

«/ 

#lnclude "exec/types.h" 
Mnclude "functlons.ti" 
#lnclude "ilbrarles/dos.h" 

ctiar ps_cmd[] = {"newpath 100 200 moveto 300 400 lineto stroice 
showpageVn"}; 

void maln() 

1 

BPTR Mie; 
long Isn; 

file = OpenC'PAR:", MODE_NEWFiLE ); 
if( Hie ) 

{ 



len = strlen( ps_cmd ); 

if( Write( llle, ps^cnd, ien ) 1= len ) 

putsC'Write erroAn"); 
C!ose< file ); 

} 

else 

putsC'Open (aliure\n"j; 

1 

GET FANCY 

A single line is nice, but nothing special. With two new 
commands, you can modify the test.ps program to draw a 
box with a different line width. 

newpatti 
100 200 moveto 
100 400 lineto 
300 400 lineto 
300 200 ilneto 
close path 
10 setiinewidth 
stroke 
show page 

The setiinewidth command specifies the width of the line 
as 10 points. The closepath operator completes the box and 
produce a flush appearance. (Replacing closepath with 100 
200 lineto will not gi-ve the same results. Because of the added 
thickness of the line, a small notch will remain at the start/ fin- 
ish point.) 

You can create a filled box as well: 

newpath 
100 200 moveto 
100 400 lineto 
300 400 Ilneto 
300 200 lineto 
closepath 
.6 setgray 
fill 
shovrpage 

Also new to this e:<ample, the setgray operator allows you 
to create grayscales. For solid black use 0, and for white use 1 . 

Without some forra of title, axis labels, and numeric scales, 
the graphs you build ivith the above commands will not be very 
useful. Enter PostScript's text-creation power, PostScript print- 
ers contain a set of standard typefaces (such as Times-Roman 
or Helvetica), but you can also instruct the printer to use type- 
faces that it does not hold internally. Wlien you wish to print, 
you must first spedty the typeface and size you want, that is, 
specify the current font. Here is a quick sample program: 

/Helvetica findlont % u se the Klelevetica typeface 

12 scalefont % malce ttiis 12 points high 

setfont % make this this current font 

100 300 moveto 

(Helio World) show % print Helio World at location 100, 300 

showpage 

Note that you place the text to be printed within paren- 
theses and use the show operator. 

ALL TOGETHER 

Now let's combine the graphic and text elements into one 
larger program that draws a filled gray box with a 10-point 
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thick dark-gray border. Above and to the right of this box it 
prints blorg[ at a 10-degree angle. (See Figure 1.) 

newpath 

% create a light-gray INIed box 

100 200 moveto 

100 400 lineto 

300 400 lineto 

300 200 lineto 

closepath 

J setgray 

till 

% outline the box with a dari(-gray border 

1 00 200 moveto 

100 400 lineto 

300 400 lineto 

300 200 lineto 

closepath 

10 setlinewldth 

.25 setgray 

stroke 

% malce a 20-polnt Helvetica font. 

/Helvetica findfont 20 scalefont setfoni 

setgray % set the inl< to blac)(. 

300 300 translate % move the origin to the position 300, 300 

1 rotate % rotate coordinate system 1 degrees 

50 1 50 moveto 

(biorgl) show % print the word blorg! 

showpage 

This example introduces two new concepts. First off, the 
translate operator lets you move the effective origin to any 
point you desire. After all, appUcations may require an origin 
somewhere other than in the lower-left comer. Also, a program 
might continually change the origin if multiple data plots or 
3-D effects are used. The rotate operator moves the coordinate 
system a given number of degrees counterclockwise. The 




above example uses this to make the text run uphill. 

Note that transposing the first two portions of the program 
will subtly alter the page. If the filled-box section is called sec- 
ond, it will obscure the inner portions of the surrounding 
border, because it is laid down using opaque "paint" (even 
when using grayscales, there is no transparency). Before mov- 
ing to the next example, try experimenting with the clip op- 
erator. The basic idea is to define a clipping path using the 
appropriate newpath /moveto /lineto /closepath commands. 
When this path is complete, finish with the operator clip. 
This sets the clipping path to the one you just defined. Only 
areas within the clipping path will be rendered. For example: 

% define a triangular clipping region 

newpath 

100 200 moveto 

150 300 lineto 

200 200 tineto 

Closepath 

clip 

Try placing this code chunk at the very beginning of the 
previous example and watch what happens (Figure 2). Note 
that the clip code affects only painting that comes after it. 




Figure 1. The setliitewldlh and setgray commands In actlcn. 



Figure 2. A trlsngular region clipped Irom Figure 1. 

If you are tired of straight lines, a useful operator is arc. Its 

general form is: 

X y radius l>egin end arc 

The command 

100 200 30 45 arc 

produces an arc centered on coordinate 100, 200 with a radius 
of 30. The arc starts at degrees from the horizontal and ex- 
tends counterclockwise back to 45 degrees. (The accn com- 
mand produces a clockwise rotation.) 

For a different perspective, consider the scale operator. Up 
to now, the default coordinate system of points C/^z inch) 
was used. You can, however, scale the user space, increasing 
or decreasing the scales as desired. For example, if you would 
like to change the scale to something larger you could say: 

100 200 scale 

which increases the X axis by a factor of 100 and the Y axis 
by a factor of 200. 

THE COMPLETE PICTURE 

Our last stop on the PostScript tour is the transfer of im- 
ages. Such operators as moveto, lineto, and arc are very use- 
ful for CAD-type programs, but they are not particularly ef- 
ficient when dealing with bitmapped images. PostScript 
solves this problem via the image operator. With it, you can » 
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transfer bitmapped images (black-and-white or grayscale). 
The image operator's general format is: 

width height blts_per_sample transform^matrtx procedure Image 

Width and height indicate the size of the image. Analogous 
to the "depth" of an Amiga screen, bits_per„sample can be a 
value of 1, 2, 4, or 8. For example, 4 means that each pixel is 
represented by a 4-bit value. A black-and-white picture has a 
bits_per_sample of 1 . The transform_matrix is rather involved, 
but in essence, it allows you to map the image data onto the 
page in a variety of ways (for example, you could make a 
mirror version). For general-purpose image data where the 
origin is at the upper left, the transform matrix is [width - 
height height]. The procedure parameter is the data to be 
used. The image operator takes all of these parameters and 
maps the image data onto a "unit square." You can change the 
aspect ratio of this square with the scale operator, 

A slightly more advanced use of the image command al- 
lows you to repeat the image (rather like a pattern) within the 
unit square. The data is organized as a series of samples, each 
being 1, 2, 4, or 8 bits in length. The value of a sample corre- 
sponds to the values associated with the setgray operator. 
That is, black is and white is 1. 

While it is possible to calculate image values by hand, it is 
tedious to say the least. A good tool to have for experimen- 
tation is a drawing utility that lets you save the picture in- 
formation as C source code, such as Icon2C on Fred Fish #56. 
Once you have drawn the picture with the tool and saved its 
data file, you must edit it for PostScript consumption. Hex 
values in C begin with Ox and individual values are separat- 
ed by conunas. Both of these elements must be removed for 
PostScript data (search /replace and macros come in very 
handy for this). 

The following program uses data derived from such a tool. 
The image is 32 by 20 and is black and white (one bitplane 
deep). The image will be drawn twice, so it is defined as an 
element called faceguy using the PostScript operator def. 



newpalh 

% Image Is 32 wide by 20 high 

/laceguy 

<tf HHff 

f0 3f00ff 

b7 9e 7e 7f 

ffffffff 

fOOfOOfI 

e7 e6 7e 7f 

cl C6 fc 7f 

67 06 78 7t 

food 00 ft 

fffcffff 

fffelfft 

e7ffceff 

871f8e1f 

e7c0 1eff 

foftfetf 

fc 00 03 ff 

(df9dfff 

fc fl df <1 

feinfff 

ff CO 7f ff > def 



100 200 translate 

72 72 scale% 1 pixel = 1 Inch 

32 20 1 [32 -20 20] {laceguy} Image 

1 2 tran5late% move right 1 Inch, up 2 inches 

2 3 sca1e% twice as wide, three times as high 
32 20 1 [32 -20 20] (taceguy) Image 

showpage 

To see the picture, the coordinate system is scaled to a 
much larger size. Also, the translate operator brings the im- 
age up and to the right. The second time the program draws 
the image, a further translation keeps the two images on dif- 
ferent parts of the papier. Note the second translate uses much 
smaller values than the first, because the user space has al- 
ready been magnified by the 72 72 scale command, A second 
scale command shows how you can stretch or distort an im- 
age. In this case, the image will be taller and skinnier than 
normal. This all worlis fine for black-and-white images. Cre- 
ating grayscale images is a bit more time consuming, how- 
ever, because most cf the available programmer's drawing 



op 



op 

Figure 3. A rep«aled pattern eieinGnt. 

tools save data bitplane by bitplane rather than producing 
values for each pixel. 

RELAX MODE 

As you can see, PostScript programming is not particular- 
ly difficult if you have already mastered another high-level 
language. Once you test your code, splicing it into the Ami- 
ga application is easy. The commands discussed here should 
be more than enough, to get you started, but if you would like 
to learn more about PostScript's power, I recommend The 
PostScript Language Tutorial and Cookbook and The PostScript 
Language Reference Manual, both by Adobe Systems Incorpo- 
rated and published by Addison-Wesley. ■ 

Jim Fiore is a member of dissidents, which specializes in Amiga 
music and audio softumre. In his spare time he enjoys numerous 
hobbies and pursuits zchich liave nothing whatsoever to do ivith sil- 
icon or C compilers. Also, he is presently putting the final touches 
on an electrical engineering text for West Publishing. Write to him 
cjo The Amiga World Tech Journal, 80 Elm St., Peterborough, 
NH 03458, or contact him on BIX (jfiore). 
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Become a part of the 

AmigaWorld 
Programming Team 



We're looking for quality programs to support the growth 

of the AmigaWorld product line, 

and we need your help. 



GAMES 

ANIMATION 

3D 

UTILITIES 

CLIP ART 

AMIGAVISION APPLICATIONS 

OTHER STAND-ALONE APPLICAnONS 



We offer competitive payment and an opportunity for fame. 
Send your submissions or contact us for guidelines: 

Amiga Product Submissions 

Mare-Anne Jarvela 

(603) 924-0100 

80 Elm Street 

Peterborough, NH 03458 
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VIDEOS 

Order now and save $5.00 off the retail price 
and get a $5.00 savings coupon good towards your next 
TechMedia Video purchase! 






The Amiga Primer 

Anyone with an Amiga - 

whether a new owner or an 

experienced user — will 

find this easy-to-1ollow video 

invaluable. Applicable to all Amiga models, 

The Amiga Primer presents System 2.0 and 

AmigaVision^" the Amiga Workbench, the CLl 

peripherals, and utilities in an entertaining 

tormat with vibrant graphics and upbeat music 

There's no easier way lo master your Amiga! 

#TMAP 90 minutes ^n^ tJH-^^ 




FREE! 

Psygnosis 
Lemmings™ 

Game 
Demo Disk 

with your order 



Newtek's Video Toaster 

Tbe Video Toaster'" from 
NewTek is hailed as the 
world's first video computer 
card enabling broadcast-qual 
ity production on desktop. 
Whether you are considering 
the purchase of a Toaster™ 
or are just curious about 
all the excitement, the 
Video Toaster'" video tape 
provides In-depth Informa- 
tion such as: 

• Installing the Toaster'" in the Amiga 2000 

• adding and testing other essential equipment 

• selecting source material and processirvg 
speed 

• manipulation of many digital video effects 
including flips, tumbles, mirrors, spins, splits 
and titles 

• producing 3-D animations 
■ painting on video images 

See for yourself what the amazing Toastef" 

can do! -.^^^ 

#TMVT 45 minutes )^f^ t]%*iS 





Hot Rod Your Amiga 

Learn how to get maximum 
power from your Amiga. Get 
valuable advice on how to 
expand memory internally 
and externally; select and 
install hard drives, 
memory boards and 
J accelerators; back-up 

^^^^ software and utilities; 
_^^fc^P^Y^^ RAM and drive space 
' ^^^ VX^J^ differences; and other 
■^^)Ji|^^^^ useful tips. Hot Rod 
'' W Your Amiga also 

f covers the revolutionary 

Video Toaster'" and other high-end 
peripherals such as DCTV. Soup up your 
Amiga now! 
#TMHR 45 minutes 



>K!t^/''-^sr 




NEW!^ 



Long 
Awaited 
Volume 



Animation Video 
Volume II 

In response to the clamor for 
another Amiga animation video- 
tape, the AmigaWorld editors 
have created Animation Video 
Volume II. After sifting through 
hundreds of contest submissions and"' 
viewing countless hours of animation clips, 
the result is a showcase of scintillating anima- 
tions, technical brilliance and imaginative 
plots. You'll be thoroughly entertained as you 
absorb new techniques and ideas. Whether 
you just brought your Amiga home from the 
store or have created your own animations 
before, you'll want to add Animation Volume II 
to your Amiga video collection! 
#TMAV2 90 minutes S?^ ^/'?.^5^ 








Desktop Video, Volume I 

Whether for home or studio use, 
Desktop Video shows you how 
to utilize your Amiga in conjunc- 
tion with a video camera to 
create professional-quality productions with live 
video and animation techniques. Learn how to 
select a genlock; build a desktop video system; 
choose and use a video camera; create scripts, 
storyboards and titles. Plus tips on editing, 
adding sound, special effects, and much more. 
A must for any video enthusiast! 
#TMDV 84 minutes SSg^ ^ZH.'K 



Call Toll-free 1-800-343-0728 

The AmipaWorld Catalog • PO Box 802 • 80 Elm Street • Peterborough, NH 03458 
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The Musical Amiga 

With detailed insight from some 
of the best-l<nown Amiga musi- 
cians, The Musical Amiga 
teacfies you how to create both simple 
tunes and complex musical compositions. 
Sessions on MIDI systems include sequencing 
editing and synthesizing. Learn the techniques 
used in digital sound sampling, sound manipu- 
lation ancJ creation o( unique sound effects. 
Accompanied by an entirely Amiga-produced 
soundtrack, this dynamic video is sure to 
eniighien you with the remarkable musical 
polenlial of your Amigal 
#TMMA 60 minutes J^S^ "^2^.95^ 



Animation Video, Volume I 

A best-selling video, containing commercially 
broadcast and award-winning animation art, 
this video will fascinate, entertain and inspire 
you as it demonstrates the amazing capabilities 
of Amiga animation. Each of the many anima- 
tions is accompanied by unique music and 
sound effects, and is prefaced by the artist's 
name and a listing of all the animation products 
used. Experiment and explore the endless 
possibilities yourselfl 
#TMAV 48 minutes ^Mfc§l ^/V.^" 



AMIGA BOOKS 



Amiga Graphics 

Amiga Graphics is all you need to explore the 
extraordinary graphics capabilities of your 
sophisticated Amiga. Learn the pros and cons 
of the most popular paint programs. Get three 
intensive sessions on fonts, clip art and digitiz- 
ing, as well as in-depth coverage on the 
elements of design and style, Amiga Graphics 
also illustrates interlace functions, when Hold 
And Modify (HAM) should be used, and covers 
smearing, washing, tinting and perspective. An 
invaluable tool for any artist! 
#TMAG 54 minutes ^SM^.T^^.^S' 




Amiga Is a isgistered trademark of Commodore Business 

Machines, Inc. 

Video Toaster Is a reglsteree) trad9mar1< o! NewTek, Inc. 




New Edition! 



AmigaWorld Official AmigaDOS 2 
Companion 

by Bob Ryan 

^, Harness the power 
of the new 
..! AmigaDOS 2! 
"^ The Amiga 
Companion is 
; back — In a 
^ revised and 
- expanded 
edition for AmigaDOS 2. 
Ifs your expert guide to the new DOS, filled 
with hundreds of instructions, tips & tech- 
niques not found In any other book. 
Covers: 

• The Amiga OS, Including Workbench, Shell 
&ARexx 

■ The Workbench GUI 

• Workbench menus and tools 

• The 1 3 Preference Editors 

• The Extras 2 disk 

■ AmigaDOS — handling disks, flies & 
devices 

■ Configuring AmigaDOS 

• Manipulating files with Copy, Delete, 
MakeDIr, Rename 

• AmigaDOS command scripts and shortcuts 

• The ARexx macro language and a fully 
annotated program to customize 

• Plus over 100 screen shots, command 
references, a valuable glossary, and an 
error code summary for solving problems 
more easilyl 

#1-878058-09-6 41 6 pages $24.95 




AmigaWorld Official AmigaVision 
fiandbook 

by Louis Wallace 

Express your aeattvity on the Amiga — with 
this complete guide to the new AmigaVision! 
TJie only authoritative guide to the hottest 
program for your Amiga. Written in an easy- 
to-follow style and heavily Illustrated, with 
over 150 screen shots, this book provides a 
step-by-step primer for mastering 
AmigaVision. 
Special Features: 

"What exactly multimedia is, the art of author- 
ing, the basic menus, common requestors, 
and program editing Information 
• Control commands covering: Interrupts, 
database icons, wait icons, audiovisual 
icons, and module Icons 
> In-depth editors, tools, and programming 
information 

■ Valuable appendices filled with advice on 
the best hardware and software products 
for AmigaVision, and a special guide to 
version 1.7. 
#1-878058-15-0 353 pages $24.95 
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Get Noticed 



Convince the press to spread the word 
on your product for you. 

By Brian Sarrazin 



YOUR PRODUCT IS going to change the face of Amiga 
computing. If people knew about the technological wonder 
you created, they would beat a path to your door offering 
gobs of cash. The problem is they either do not know about 
your product or know about it but do not fully understand 
what it can do for them. So how do you get the word out? 

Blanketing the market with ads and trade show demos will 
get you name recognition, but at a hefty price. If your bud- 
get is small, you are better off talking someone into doing the 
shouting for you for free. You need to convince the press to 
cover your product. Before you start dialing the phone, how- 
ever, take these hard-learned lessons to heart. 

SPEAK THE LANGUAGE 

First, consider the perspective of your target audience and 
the context within which the message is delivered. You must 
understand how to speak the language of your listener to be 
understood. Communicating in a manner that is consistent 
with your audience's thinking style will also help. 

With these thoughts in mind, you are ready to tailor your 
message to the experts in the press who can cover your prod- 
uct — the editors. Look at the mastheads of your favorite Ami- 
ga magazines. The editors listed are the people who will help 
you, if you help them first. 

Editors pride themselves on objectively surveying the mar- 
ket and delivering important information to their readers. If 
editors feel that many people will benefit from your product, 
then it has a high level of newsworthiness. Make no mistake, 
a high level of newsworthiness is like having money in the 
bank. To convince them, you must tell the editors the benefits 
your product can deliver. To do this, study each magazine 
covering the Amiga market (and perhaps a few that cover the 
vertical market your product falls into), create and send the 
proper communication devices, and follow up appropriately. 

Start by analyzing the magazines to garner an idea of the 
type of things the editors feel are important. It will also help 
to understand the editorial style. Read the feature articles in 
recent issues with an eye to grammar as well as to content. 
Look at the products reviewed. Scrutinize the helpful hints 
section for ideas on the type of issues the readers are 
wrestling with and, consequently, the concerns of the editors. 

To further help you understand the editorial perspectives, 
request a media kit from each magazine. Inside the kit 
you'll find an editorial calendar outlining the magazine's 
planned emphasis for the coming months. Look for areas 
that your product may fall into and time your correspon- 
dence accordingly. 

Learn the responsibilities and style of every editor on the 
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masthead. Each will have a different reason for being inter- 
ested in your product. The new products editor hopes to cov- 
er all that's new. The review editor hopes to coordinate and 
deliver objective summaries of key products' effectiveness. 
The features editor is interested in how products fit into key 
areas of functionality. Once you understand their interests 
and concerns, you are ready to contact the editors. 

Editors prefer to be contacted first with printed matter, a 
press release and a cover letter. If you tailor your material to 
each one's style and perspective, you help them determine 
more quickly whether your product warrants coverage. Once 
decided, an editor may be interested in spending some time 
uncovering the details via the phone. 

PUT rr ON PAPER 

The press release is by far your most important tool to 
catch the editor's attention. As you only have about two sec- 
onds to do so, use your time wisely. Objecti\'ely report the 
facts and answer the five basic questions — who, -ivhat, when, 
where, and why — in as few words as possible. Tlie pyramid 
approach is best: First supply the bare facts, then present the 
facts with some elaboration, and finally give the facts with 
significant elaboration. The most difficult part will be keep- 
ing your statements objective. You know how tremendous 
your product is, but you must contain your enthusiasm. 
There is no room for subjective opinion in a press release. 

Structure the page for a quick read. The first line should tell 
the editor who to contact for more information. Underneath 
the name, list the phone number only. Next, you should in- 
dicate when the information may be released to the public, 
usually "FOR IMMEDIATE RELEASE." After this comes the 
headline, which must get attention. Indicate the most note- 
worthy aspect of your product here with a minimum of 
words. Adjective count: zero. Write that your company an- 
nounces (or begins shipping) Product A and then state your 
most important reason for creating it. Double-space the re- 
maining copy and leave generous margins to give the editor 
plenty of room to make notes. 

Write the press release to mirror the target magazine's 
style, so the editor merely has to cut and polish it to suit the 
magazine's new products or news column. This helps the 
editor and it helps you communicate more directly to poten- 
tial customers who read the magazine. Your goal is to write 
a press release that the editor does not have to change at all. 
Keep in mind, however, editors often will not print what 
they cannot confirm. If your product is not in the editor's 
hands, do not be surprised if your confident "WonderDrive 
is three times faster than existing drives" is changed to 



"WonderDrive claims to be three times faster than existing 
drives." 

Keep the first paragraph compact. Start by stating where 
the newsworthy event took place: where you began shipping 
your product or made an announcement. Was it at company 
headquarters, a trade show, a special press conference? Next 
indicate the date of the event. You have now covered the 
who, what, when, and where. Next, expand by more fully de- 
scribing the what. For example: 

New York City, New York, September 1, 1990 — Big Time 
Publications today announced a new magazine to be called 
Laimt Care lotinial. Starting with its first issue in early 1991, 
Lawn Care journal will cover items of interest to professional 
groundskeepers and wiU be edited by Jean Hobbs. 

In the second paragraph introduce the why. Why will the 
Amiga community benefit from your product? Because the 
answers lean toward the subjective inherently, a quote does 
the job best. For example, just fill in the blanks of the sample 
template below; 



"We feel there is a tremendous need for 



based 



on what we hear during on-line roundtable discussions. For 

this reason, we have created the first for the 

Amiga computer. It will revolutionize the way people 
," said , president of . 

The remaining paragraphs should go into increasingly 
greater detail and should include another quote. Don't get car- 
ried away; a press release should rarely be greater than 300 
words. The above two examples total nearly 100 words already. 

The cover letter lets you get into the why in detail and is 
essentially your opportunity to persuade the editor that your 
product is very newsworthy. Tailor each letter to the needs 
of the editor receiving it. Do not print 20 cover letters and 20 
press releases and send them out to "Editor" or "Dear Sir." 
This is sure to alienate as it indicates a low level of concern 
for the editors' individual interests. A half-hearted effort will 
get you the results it deserves. 

Remember: The less hype the better. Start your letter with 
a brief, 25-word statement of why you created your product. 
You should be able to use the first quote from your press re- 
lease. If you can't, rethink your press release. In the second 
paragraph weave key features into your discussion of how 
you solve the users' needs. This shows that you put serious 
thought into the features you included, and maybe the ones 
you left out as well. 

ILLUSTRATED BY LAURA STEARNS JOHNSON 




If your product is shipping, send it with the press release 

and letter. This gives your statements more weight, as the ed- 
itors can see your product is real. If the product is still in de- 
velopment, send review copies as soon as it is ready. Do not 
fall prey to the "If they want to look at it, they can buy it" phi- 
losophy. If you do, your product will be relegated to obscu- 
rity, Remeniber, the press is helping you. They communicate 
with a very large group of Amiga users for you. Give away 
review copies liberally. In the case of hardware, simply loan- 
ing a unit is acceptable. You are still better off, however, send- 
ing a copy for keeps. That way the editors will have your 
product on hand if they schedule a related article a few 
months after it was released. Don't send a crippled version. 
Tlie people of the press are professionals. You insult their in- 
tegrity by sending a disabled version. 

The last item to slip into the press package is a picture of 
the product, the packaging, or a sample screen. Look through 
the magazine to see which is preferred. The picture should 
be in slide format and on a disk as an IFF file. 

FEEL FREE TO CALL 

Follow-up phone calls are your next step. Again, vary the 

timing and purpose based on each editor's needs. 

New products editors move at a quick pace. They have too 
much to report and not nearly enough time. Show you un- 
derstand their time constraints. Make sure the significance of 
your product is evident from reading the press release alone. 
Limit your follow-up call to introducing yourself, ensuring 
that the package was received, and inviting the editor to call 
you back if needed. The timing here is critical. The sooner you i 
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Get Noticed 

call, the better, but do not call until you are sure your pack- 
age is on the editor's desk. Sending the material via overnight 
or second-day express is very effective. 

Review editors look for in-depth information. Do not at- 
tempt to provide it all in the press release, but make sure to 
explain why your product advances the state of Amiga com- 
puting, not merely why you made it. Follovv-up is very im- 
portant. Remember that a fair review could be the best thing 
that ever happened to your product. Your objective should 
be to clarif)' the reasoning behind your product and to de- 
termine where to send review copies. You will probably be 
asked for two copies. One will be for the editorial office and 
one for the person writing the review. (Do not ask for the re- 
viewer's name; this is not professional.) Allow a couple of 
weeks to pass before calling. Realize that there are too many 
products vying for too little space and scheduling is a key 
aspect of the review editor's job. A two-week delay between 
receipt of the package and your call reflects your under- 
standing of this. When asked for a review copy, send it ex- 
press and call to ensure it arrived on schedule. Always no- 
tify the review editor of any updates that might affect a 
potential review or one in progress. 

Features editors look for the most comprehensive infor- 
mation and work the furthest in advance. Consult your edi- 
torial schedule and look at the feature articles or issue themes 
conung up. Find one that most closely fits your product and 
explicitly mention the relationship in your cover letter. Indi- 
cate precisely how your product fits into the area to be dis- 
cussed. (Keep the magazine's lead time in mind, however; ed- 
itors often are working on issues four or more months ahead 
of the cover date.) A couple weeks after you send your pack- 
age, call to ensure it arrived and offer to send anything else 
the editor might need for upcoming articles. Watch the edi- 
torial calendar and call again about the time the features ed- 
itor plans the issue for which your product is appropriate. As 
for the review editor, alert the features editor to updates to 
the product that might affect coverage. 

DON'T TAKE IT PERSONALLY 

If you encounter editorial resistance to covering your prod- 
uct, do not become defensive or hostile. These people know 
more about the needs of their readership than you do. Your 
job is to make the benefits of your product clear. If you have 
done so and the editor decides that it is not worth covering, 
you have just received a very valuable lesson. Find out why 
they feel as they do. Perhaps they could direct you to a more 
appropriate magazine to cover your product. 

If the editors decide to mention your product, find out ex- 
actly when the issue it is appearing in will be on the shelves. 
Time your discussions with other key community players 
(such as software resellers or publishers) with the release of 
the magazine; it will add credibility to your product. 

The importance of communication cannot be overempha- 
sized. No one will be interested in your product if they do not 
understand what it can do for them, if you think in terms of 
helping the experts who can help you, you will earn the press 
coverage your product deserves. The result will be throngs 
of Amiga owners beating a path to your door offering gobs 
of cash. ■ 

Brian Sarrazin is the Western Regional Manager for RGB Coin- 
pufer & Video. Write to him cjo The AmigaWorld Tech Journal, 
80 Elm St., Peterborough, NH 03458. 
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Start-up Messages 

Pay attention, maybe your Amiga is trying 
to tell you something. 



By David W. Martin 



AS YOU NO doubt have noticed, when you boot under OS 

1 .3 your screen flashes a series of colors. Aside from simply 
loading the Workbench, your Amiga goes through a series of 
initialization and test procedures when you turn the power 
on or reboot. Not simply reassurance that "something is hap- 
pening," the colors provide information on the results of 
these tests. Watch the flashes: If you learn how to interpret 
the colors, they can provide early warning signs to system 
failures. 

Each time you boot, your system conducts the verification 
and initialization steps below: 

1. Clear hardware data registers (custom chips, and so on) 
of old data. 

2. Disable interrupts and DMA during testing procedure. 

3. Clear the screen display. 

4. Test the hardware and check that the CPU is working. 

5. Change screen color to show the results. 

6. Perform a checksum test on ROM. 

7. Change screen color to show results. 

8. Begin the system startup begins. 

9. Test the SCOOOO RAM and place SYSBASE 
information there. 

1 0. Conduct a test on chip RAM. 

11. Change screen color to show results. 

12. Test to check if software is coming v«thout errors, 

13. Change screen color to show results. 

14. Prepare chip RAM for data. 

15. Link Amiga libraries. 

16. Test for and additional memory expansion 
and link it if found. 

17. Restore interrupts and DMA. 

18. Begin execuHon of a default start-up task. 

19. Test for usage of a 68010, 68020, 68030, or 68881/2. 

20. Test for exception (or processor) error. 

21. If an exception occurs, reset the system. 

A healthy system flashes the following sequence on screen 
as the tests proceed: 

Dark gray 
Light gray 
White 

The first color indicates that the CPU test was passed and 
the 680x0 is up and running fine. The second reassures you that 
the software is corning in without problems. Finally, the white 
flash signals that the system passed all initialization tests. 



Upon encountering trouble, the system changes the screen 

to one of the danger sign colors and halts all activity. A red 
screen indicates a ROM checksum error occurred. Green de- 
notes an error in chip RAM, while blue tells you one of the 
custom chips has a problem. A yellow screen reports that the 
680x0 found an error before the system's error- trapping soft- 
ware (guru) was started. While you probably will never re- 
ceive an error message, the most common is the green screen. 
Many early Amiga 500s had loose Agnus chips, which caused 
chip RAM errors. Gently, but firmly, pushing in the chip usu- 
ally solved the problem. 

A SYSTEM ALL ITS OWN 

While the CPU is the most obvious about its activities, your 
keyboard undertakes its own start-up sequence when you 
power up or reboot. A self-contained system, an Amiga key- 
board houses a CPU, 2K of ROM, 64 bytes of RAM, four 
eight-bit I/O ports, and a timer, all of which are monitored 
by error checking and initialization software. When you boot 
your machine, the keyboard routines: 

1. Check ROM with a ROM checksum test. 

2. Check RAM with a RAM test. 

3. Check the timer to ensure it is functioning. 

4. Syncfu-onize the keyboard with the computer. 

To alert you to any errors it encounters, the keyboard 
blinks the light on the Caps Lock key. The number of blinks 
identifies the error. The blink code is: 

One Keyboard ROM checksum failed. 
Two Keyboard RAM test failed. 
Three Keyboard watchdog timer test failed. 
Four A short exists between two row lines or one of the 
seven special keys (currently not implemented). 

Chances are you will never encounter an error flash or 
blink. If your system does start acting strangely, however, 
pay close attention at startup for these warning signs. While 
they will not tell you the whole problem, they will point you 
and your repair technician in the right direction, saving him 
time and you money. ■ 

David W. Martin is the nuthor for the 1581 DOS Reference 
Guide and a frequent contribufer to Amiga publications. Write to 
him c/o The Amiga World Tech Journal, 80 Ehn St., Peterbor- 
ough, NH 03458, or contact him ou PeopleLink (davidm), Compu- 
Serve (72510,3232), or Usenet (davidm@liackercorp.com). 
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From p. 37 

event MouseXC) but everit_menu- 
subitemO. There was no index. The 
documentation appears to have been 
set up for on-line browsing rather than 
paging through a printed copy; the 
files are organized one per routine in 
object-grouped subdirectories, which is 
only good if you have hard-disk space 
to spare and a multiwindow editor. 

I tried the package with SAS/C 5.10 
and Aztec C 5.0a, by adapting some 
existing code. The sources with 
amigaview.h included compiled ac- 
ceptably, the objects linked, and the 
executables ran. I didn't notice any 
obnoxious slowing, and the gadgets 
and menus worked just fine. The add- 
on size of the library was not out of 
line with what I expected. 

Using AmeegaView routines re- 
duced typing time, and to some extent 
simplified the edit-compile-test cycle. 
Don't expect a no-brain solution, 
however; you can't use the routines 
without knowing what Intuition does 
and what its data structures specify. 
New programmers will still have to 
learn window and screen setup and 
Intuition/ AmigaDOS message pro- 
cessing. AmeegaView merely makes it 
easier to deal with the nitty-gritty of 
typing in and compiling all those 
specifications. It will make your pro- 
grams a little more readable and a 
little easier to test. It won't make 
Intuition any less complex. 

AmeegaView is a good package, but 
a real manual and better naming con- 
ventions would make it a better one. 

AmeegaView 

ACDA Corp. 

220 Belle Meade Ave. 

Setauket, NY 11733 

516/985-1700 

$79.95 

No special requirements. 

MINIX 1.5 

A little Unix for the Amiga. 

By Stephen R. Fietrowicz 

A UNIX-COMPATIBLE operaHng 
system, MlNlX (which stands for 
Mini-Unix) was written by Andrew 
Tanenbaum, a professor at Vrije 
Universiteit in Amsterdam, The 
Netherlands, as a teaching tool for his 



classes. The Amiga version of MINIX 
offers a relatively inexpensive way to 
learn how an operating system, and 
Unix in particular, works. 

Amiga MINIX is actually a port of a 
port. The original IBM PC version of 
MINIX was ported to the Atari ST, 
and that version was ported to the 
Amiga by Raymond Michels and 
Steven Reiz. Interesringly enough, 
under MINIX, the Amiga and Atari ST 
can exchange and run binaries with- 
out modification. 

You'll find most of what you'd ex- 
pect on a regular Unix Version 7 sys- 
tem in MINIX and a good working 
knowledge of Unix and it's utilities is 
essential. The package includes nearly 
all of the standard Unix utilifies (over 
175), a Bourne shell work-alike, a K&R- 
compatible C compiler, five editors, 
and over 200 library procedures. Addi- 
tionally, because the utilities and the 
operating system code were written 
from scratch, MINIX can be sold with- 
out having to deal with licensing re- 
strictions for the source code. In addi- 
tion, the package includes complete 
source for everything except the C 
compiler and one of the text editors. 

MINIX will run on a one-megabyte 
Amiga 500 or an A2000, and it will 
also recognize expansion RAM and 
extra floppy drives. MINIX does not, 
however, support the 68020, 68030, or, 
in the release version, hard drives. 
However, there is a beta version of 
MINIX that supports the A590 con- 
troller for the Amiga 500. If you have 
access to Internet, you can download 
the beta version that supports the 
A590 from star.cs.vu.nl at address 
192.31.231.42. (It's probably also avail- 
able at the sources mentioned later in 
this review.) Even if you don't have an 
A590 controller, I encourage you to 
find the new binary of MINIX. It 
seems to make the floppy disks work 
much more reliably. 

SETUP 

MINIX comes on nine disks — one 
{your boot disk) in AmigaEXDS format 
and the rest in IBM format. You can 
use a commercial or PD IBM disk- 
copying program, or use the MINIX 
"diskcopy" command after booting 
MINIX to make backups. If you use the 
latter method, you must first format 
the backup disks using the transfer 
utility before booting MINIX. Format a 
few extra disks, because the Amiga 
version of MINIX doesn't have a for- 



matting utility. If one of the disks is 
bad, you'll have to reboot AmigaDOS 
to reformat another. I usually keep a 
few extra disks formatted to avoid 
having to reboot. MINIX seems to be 
very particular about its floppy disks, 
and it rejected many that 1 tried. 

When the system boots, it loads the 
root partition completely into RAM. 
The other partitions, such as /usr, can 
then be mounted on one of the exter- 
nal floppy drives. You can also in- 
crease the root partition's size to allow 
more binaries to be loaded into RAM 
and significantly increase the speed at 
which programs will load and run. 

UTILITIES 

MINIX comes writh many utilities 
(disk utilities, text formatting utilities, 
communication programs, and more), 
and most work well. For example, I 
used kermit to test the serial device. 1 
was able to dial up a local Unix system 
and transfer files back to my own 
system without any problems. 

A few other utilities, such as the vi 
editor, didn't perform as well on the 
first try. The /usr disk as distributed 
■was not set up correctly; a directory 
that vi uses to store its temporary files 
was missing. After I created the direc- 
tory, all went smoothly. 

I also had a problem trying to ex- 
tract some of the source-file archives 
while attempting to recompile the 
entire operating system. All of the 
source comes in compressed archives. 
Decompressing the archives seemed 
to work correctly, but when I tried to 
extract the source from the resulting 
files, I didn't get very far before re- 
cei\'ing an error message. I tried at 
least five times with the file-system 
source archive, and each time 1 re- 
ceived a different error message. Be- 
cause I was unable to overcome that 
problem, 1 was unable to recompile 
the OS as 1 had hoped. I should also 
note that not all archives exhibited this 
problem. I was able to extract some of 
the source from different archives. 

The need for hard-disk support was 
very evident when I started using the 
compiler. It expects to run out of the 
/usr directory, and because the com- 
piler and the utilities on the /usr disk 
won't all fit on one disk, I had to rear- 
range things a bit to get a working 
compiler disk. Luckily, most of the 
compiler disk is already put together, 
so it isn't that difficult. Compiling 
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programs on floppies is pretty slow, 
though. A simple four-line "hello, 
world" program took 1 minute and 45 
seconds to compile to executable. 

THE MANUAL 

Amiga MINIX users will find the 
manual a bit disappointing, because it 
contains very little Amiga-specific 
information. Amiga owners are almost 
always referred back to the instruc- 
tions for the Atari ST. To be fair, most 
of the information supplied will work 
for the Amiga, but there are a few 
things in the manual that are just plain 
wrong. For example, the information 
on creating a larger root partition is 
incorrect for the Amiga. When I fol- 
lowed the Atari ST instructions (as 
advised), I was unable to get MINIX 
to complete loading the RAM disk 
and then ask for the /usr partition. 
Everything hung up after loading the 
RAM disk. After a little experiment- 
ing, I found that using a different 
device name for the floppy disk I was 
creating worked. The manual recom- 
mends running a system verification 
test when you boot MINIX for the first 
time. I tried to run the test, but it 



wasn't even included on the disk! 

The rest of the manual looked fine. 
It contains a complete explanation for 
each of the commands, along with 
examples. There are also extended 
pages for more complicated utilities 
such as kermit and the text editors. 
Plus, the manual has a brief, two-page 
explanation of the 49 system calls that 
MINIX supports and the source listing 
for most of the OS. 

SUPPORT 

You can get your MINIX questions 
answered from a variety of sources. 
The best is the comp.os.minix news- 
group on USENET. You can speak 
directly with Andrew Tanenbaum, as 
weU as Steven Reiz. The group is in 
the process of reorganization, so by the 
dme you read this, there will be a 
separate group for binary and source 
distributions. If you don't have access 
to USENET, you can participate in 
MINIX discussions on the Mars Hotel 
BBS, 301 /277-9408. If you live outside 
the US, call NLMUG-ONLINE in 
Holland at (02522) 18363. 

For more in-depth information about 
MINIX, you can pick up the book 



Operating Systems: Design and Implemen- 
tation by Andrew Tanenbaum, from 
Prentice-Hall. Although it refers to an 
earlier version of MINIX, most of the 
concepts still apply. If you plan to do 
any serious work with MINIX, I recom- 
mend you get the book. 

FINAL THOUGHTS 

I have mixed emotions about 
MINIX. Tlie package has a lot of 
promise, but it falls short in some 
areas. For example, such features as 
networking and hard-drive support 
that are supported on other platforms 
are not available for the Amiga. I hope 
this is rectified in the next version. If 
you don't have access to any of the 
support sites listed above, you'll have 
a hard time with MINIX and I suggest 
waiting for the next release. ■ 

MINIX 1.5 

Microservice Customer Service 

Simon &: Schuster 

200 Old Tappan Rd, 

Old Tappan, NJ 07675 

800/624-0023 

$169 

One megabyte required. 



Graphics Handler 

From p. 16 

functions in your input-event loop lets you properly handle 
special GadTools operations. These functions also return use- 
ful information in the Code field of the IntuiMessage. For ex- 
ample, the actual position of a scroller or slider is provided in 
tliis field, as well as the color selected from a Palette gadget. 

When you finish your gadget list, you can dispose of the 
entire affair with a single call to FreeGList( ), passing the orig- 
inal gadget list pointer provided to CreateContextO. 

GadTools are not only simple to create and use, they are 
also easy to enhance and modify. Because of the amount of in- 
formation on GadTools gadgets alone, I did not go into Gad- 
Tool's new menu facility (which greatly simpUftes menu cre- 
ation, see David Joiner's article, "Menus for a New 
Generation," p. 4, April /May '91) and some of the other fea- 
tures and factors of using GadTools. If you wish to dig deep- 
er into the mechanics of GadTools, I suggest you study your 
2.0 GadTools header files. 

It is important to keep in mind that GadTools is not com- 
patible with OS 1 .3, so take care when using this powerful li- 
brary. Ideally, you should provide a backup arrangement us- 
ing standard gadgets. If you cannot do that, request 2.0 
explicitly, and then exit gracefully if it is not available. If you 
intend to sell your software commercially or distribute it 
widely in the Amiga market, you would do well to consider 
1.3 compatibility a must — at least for now. ■ 

Paul Millerhas been a dmeloper since 1985. Write to him c/o The 
AmigaWorld Tech Journal, 80 Elm St., Peterborough, NH 
03458, or via Internet (pmilier ©vttcf.cc.vt.edu). 
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step Up To The Podium! 



Adirdt it. You're an expert. You know how it works better than (almost) any- 
one. When you write code, you play by all the rules, yet your programs consis- 
tently out perform even those of the most wild-eyed ROM-jumping hacker. It's 
been obvious to you for some time that you should sit down at the keyboard, fibre 
up your trusty text editor, and write an article explaining exactly how and why it 
should be done your way. 

If the above description seems to fit you to a T, perhaps we should be talking. 
The AmigaWorld Tech Journal is looking for technical writers who have expertise in 
one or more areas and have a burning desire to share that information with the 
Amiga technical community. We need experts in all aspects of programming the 
Amiga, from operating systems to graphics to the Exec. You can write in any lan- 
guage you like— C, Assembly, Modula n, or BASIC. Best of aU, you can include as 
much source code as you need, because all source and executable is supplied to 
the reader on disk. We also need hardware maestro's who can explain— in thor- 
ough detail— the inner workings of such complex components as the Amiga's 
chip set, expansion bus, and video slot. Don't forget algorithms either, we'll help 
you pass on your theories and discoveries. 

The AmigaWorld Tech Journal offers you an unparaUed opportunity to reach the 
Amiga's technical community with your ideas and code and to be paid for your 
efforts as well. So, whatever your "it" is that you want to write about. The Tech 
Journal is the place to publish it. 

We encourage the curious to write for a complete set of authors guidelines and 
welcome the eager to send hardcopies of their completed articles or one-page 
proposals outlining the article and any accompanying code. Contact us at: 

The AmigaWorld Tech Journal 
80 Elm St. 

Peterborough, NH 03458 
603/924-0100, ext. 118 
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Ray Tracing 

From p. 30 

owchkO (in math.h), which creates a ray extending from the 
intersection point to the light source. It then checks to see if 
any polygons intersect the ray. (See Figure 12.) 

If it finds an interesection, the function returns true indi- 
cating that the light is blocked and the point is in shadow. If 
the point is in shadow, the color is set to a very dark brown, 
otherwise it is set to a much lighter shade. 

If a ground hit is not detected but polygon hits were, we 
call the shadepointO function (in math.h) to shade the inter- 
section point. ShadepointO uses the vector dot-product op- 
eration to calculate the cosine of the angle between the in- 
coming light ray and the intersected polygon's surface 
normal. The size of the angle determines the brightness of the 
surface at that point. In addition, the function checks if the 
point is in shadow. If so, the intensity of the surface point is 
reduced to account for the lack of light. 

If we do not find a ground or polygon hit, the sky is visible 
for the pixel. In this case, tracer calls shadeskyO (in math.h) to 
calculate a sky color. For effect, this routine shades the sky as 
though it has a different color at the zenith than at the horizon. 
Again using the dot product, the funcHon calculates the cosine 
of the angle between the ray and the ground's normal. The 
greater the angle, the more the horizon color is used, and the 
smaller the angle, the more the zenith color is used. A simple 
linear interpolation mixes the two colors. 

After the color for the current pixel is calculated, the pro- 
gram calls storeRGBO to store the color's RGB values in the 
global RGB buffers. To finish the tracing of the pixel, its color 
on the screen is turned to gray. The loop then continues to pro- 
cess the remaining pixels in the same manner. 

As you can see, we have to deal with pixels only on an in- 
dividual basis. This means that the entire ray-tracing process 
breaks down to the question, "What does this pixel's ray 
see?" It is the sophistication with which you answer this ques- 
tion that determines the quality of the resulting image. 

When all the pixels have been traced and the tracing is 
complete, the program calls the last function, writeRGBO 
(located in write.c), and passes it the object's file name in the 
same manner as for the loadobjectO function. WriteRGBO 
writes each RGB buffer as a separate file. Each file is giv- 
en the same name as the object, with a .red, .grn, or .blu 
suffix appended to it. These RGB files contain the final 
image and can be viewed using View (in the Wagner 
drawer) or The Art Department (TAD) from ASDG. In 
TAD, separate red, green, and blue RGB files are referred 
to as the Sculpt format. 

LOOKING GOOD 

Although our trip was a simple one, you can make ray 
tracing more sophisticated in many ways. Tlie best example 
is the shading function. A more powerful shading function 
would take into account variable surface attributes and tex- 
tures. This, by itself, would create much more realistic im- 
ages. In addition, you could add reflection and transparen- 
cy/refraction to increase the quality even more. With a little 
ambihon, you can turn out beautiful ray-traced images with 
your own program. ■ 

Brian Wagner, oiw of the founding members of Cryogenic Soft- 
ware, is fJic developer of 3-D Professional. Contact him cjo The 
AmigaWorld Tech Journal, 80 Elm St., Peterborough, NH 
0345S, or via PeopleLink (CRYO) or CompuServe (72137,573). 
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LETTERS 



Flames, suggestions, and cheers from readers. 



HLL 'EM UP 

I liked your first issue, but 1 have a 
few suggestions for improving the disk. 

1 . Do not have icons that open to 
show an empty window, 

2. Put a ReadMe file in each directory. 

3. Include a contents file (a la Fred 
Fish) with page references to make 
locating the associated article easier. 

These minor changes would make 
things much better, espedally if the 
disk gets separated from the magazine. 
Urban Ludwig 
Laurel, Maryland 

As you can see from this issue's disk 
(and the June/ July issue's), we have made 
some changes. Drawers in the Articles 
director]/ are noio labeled with the au- 
thor's name and the page number of the 
related article for quicker reference be- 
tween the text and code. Every drawer 
also lias a ReadMe file (with an icon), 
listing the files the directory contains and 
other pertinent notes. The neio ReadMe 
file in the root directory holds Inte-break- 
ing additions and corrections that didn't 
make it into print. Finally, we moved 
Lharc into the main directory for easier 
access. If you can think of any other im- 
provements, let us know. 



SHARED STRIPS 

In "Menus for a New Generation" 
(p. 4, April/May '91), David Joiner 
implies that having windows share 
menu strips is a quick way to get a 
guru. While this is generally true, 
there are special cases where it is false, 
such as when the hvo windows are 
also sharing ports. While making this 
work right is tricky, it is a worthwhile 
thing to know how to do. 

Mike Meyer 
Palo Alto, California 

You can have two windows sharing 
the same menu strip, at least under 1.3 
and below. I am providing two short 



programs as documentation for my 
assertion- (See the Letters drawer on 
the accompanying disk.) The first, 
MenuShare, opens three windows on a 
custom screen and attaches the same 
menu strip to each. The second, Menu- 
List, displays all screens, windows, 
and attached menu strips known to 
Intuition. Tlie address of the Menu- 
Strip structure is displayed in hexadec- 
imal format. 1 suggest you open a 
couple of disks and other \\indows on 
the Workbench screen. You wU find 
that Intuition itself uses the same 
MenuStrip for each of its windows! 

Fred Scheifele 
Hamilton, New Jersey 

I stand corrected. Menus can be shared 
if all the ivindows are managed by the 
same task and have the same UserPort. 

David Joiner 



BETTER DOCS, PLEASE 

The lack of proper system docu- 
mentation has been a great contributer 
to the failure of the Amiga to catch on. 
The Amiga is a difficult machine on 
which to program — not because of the 
language of choice (C), but because 
system documentation is inadequate. 
With an operating system that is 
ROM-based, changes in the OS invali- 
date much of the existing documenta- 
tion, and new documentation lags too 
far behind the OS releases. 

Too much of the "how-to" docu- 
mentation for the Amiga consists of 
poorly translated European texts, 
often containing Httle content. Even 
the "real reference materials" fail to 
present all necessary information 
(such as library references, precedents 
of function calls, addressing modes, 
and so on), or present the information 
in an unorganized, hard-to-follow 
fashion. 1 know of many potential 
developers who simply gave up trying 
to write software for this system. 

For the machine to succeed, more 
users are needed. To get more users, 
more quality software is needed. To 
get more quality software, more de- 
velopers are needed. To get more 



developers, we must make it worth 
their time and effort to pursue an idea 
and turn it into an application. 

Thomas R. Clark 

Utiion City, California 



LIBRARY LAMENTS 

1 hoped the article "Shared Libraries 
for the Lazy" (p. 30, April/May '91) 
would help me with my shared li- 
brary project. Several times I tried 
unsuccessfully to build a shared li- 
brary include file with Manx-style 
pragma statements as shown in the 
comment section of the example pro- 
gram Simple.c. If 1 modified the .fd file 
to show which register to use I always 
got an error message and no pragma 
statements. Only if the function defini- 
tion had no arguments did LibTool 
write a pragma statment. 

Alfred Steele 
San Antonio, Texas 

The proper procedure for using LibTool 
with register args and Manx 5.0 is as 
follows: First, alter the .fd file to include 
the desired register placement. For Sim- 
ple.c, for example, the functions would 
look like: 

Add2Numbers(num1 ,num2)(d0,d1 ) 
Sub2Numbers{num1,num2HdO,d1) 
Mu1t2Numbers(num1 ,num2)(d0,d1 ) 

Invoke LibTool as noted in the starting 
comment section of Simple.c. Remember to 
include the pragmas in the header file for 
both the library and the application, other- 
wise, the compiler won't know lohere you 
want the args placed. 

Jim Fiore 



WHAT'S ON YOUR MIND? 

We're ready to listen to your sugges- 
tions for the magazine or Amiga develop- 
ers, complaints, or cries for help ivith 
technical issues. Just write to Letters to the 
Editor, The Amiga World Tech Journal, 
80 Elm St., Peterborough, NH 03458, or 
speak your mind in The Amiga World 
Tech journal conference (A W.Tech- 
Journal) on BiX, Letters and messages 
may be edited for space and clarity, m 
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A source of technical 

information for the serious 

Amiga professional. 



Iniroducing The AmigaWorld Tbch Journal, 
the new source lo turn to for the advanced 
technical information you crave. 

Whether you're a programmer or a 
developer of software or hardware, 
you simply can't find a more useful 
publication than this. Each big, bi- 
monthly issue is packed with fresh, 
authoritative strategies and advice 
to help you fuel the power of your 
computing. 

Trying to get better results from 
your BASIC compiler? Looking for 
good Public Domain programming 
tools on the networks and buHetin 
boards? Like to keep current on 
Commodore's new standards? Want 
to dig deeper into your operating 
system and even write your own 
lioraries? Then The AmigaWorld Tech 
Journal is for you! 

Our authors are programmers themselves, sea- 
soned professionals who rank among the Amiga 
communily's foremost experts. You'll benefit 
from their knowledge and msigh! on C, BASIC, 
Assembly, Modula-2, ARexx and the operating 
system— in addition to advanced video, MIDI, 
speech and lots more. 

Sure, other programming publications may in- 
clude some technical information, but none 
devote every single page to heavyweight tech- 
niques, hard-core tutorials, invaluable reviews, 
listings and utilities as we do. 







Every issue includes 

a valuable companion dislil 

And only T/ie AmigaWorld Tech Journal boasts 
of a technical advisory board comprised of in- 
dustry peers. Indeed, our articles undergo a 
scrupulous editing and screening process. So you 
can rest assured our contents are not only 
accurate, but completely up-to-date as well. 

Plus! Each issue comes with a valuable compan- 
ion disk, including executable code, source code 

Tlic AmtqaWorld 

TECH JOURNAL 



and the required libraries for all our program 
examples— plus the recommended PD utilities, 
demos of new commercial tools and other helpful 
surprises. These disks will save you the time, 
money and hassle of downloading PD utilities, 
typing in exhaustive listings, tracking down errors 
or making phone calls to on-line networks. 

In every issue of The AmigaWorld Tbch Journal, 
you'll find. . . 

• Practical hardware and software reviews, in- 
eluding detailed comparisons, benchmark 
results and specs 

• Step-by-step, high-end tutorials on such topics 
as porting your work to 2.0, debugging, using 
SMPTE time code, etc. 

• The latest in graphics programming, featuring 
algorithms and techniques for texture mapping, 
hidden-line removal and more 

• TNT (tips, news and tools|, a column covering 
commercial software, books and talk on the 
networks 

• Programming utilities froin PD disks, bulletin 
board systems and networks 

• Wise buys in new products— from language 
system upgrades to accelerator boards to edit- 
ing systems and more. 

The fact is, there's no other publication like The 
AmigaWorld Tkcb Journal available. It's all the 
tips and techniques you need. All in one single 
source. So subscribe now and get the most out of 
your Amiga programming. Get six fact -filled 
issues. And six jam-packed disks. All at special 
Charter savings. Call 1-800-343-0728 or complete 
and return the savings form below-todayf 
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"The Toaster pro\ ides a wider r:in.s;e 
ot fiiiK'tions Ifiiin :iiiy ciinihitiiUion ot 
soliilioris found on (Mats or I'Os) — 
and a( a f'rartioii of the cost. It could 
do for personal and corporate \ideo- 
lape publisliitis; what (Jutenherii did for 
the printed w(»rd'.' 

- Conilmh'r C.iinviits 

■■(Icniiniodores Amii;:i conipoler 
plalforni may have foinid iheappMeation 
it's heen lookinj; for witli the 
Video Toaster!' 

-liijhWbyld 

"provides broadcast quality desktop 
video at a heretofore unheard-of price!' 

- 'li'k'riskm HmidatsI 

"poised to j*»in the camcorder and ^(]R 
as a home video appliance!' 

- \'k/c(ti^niphy 

"took the National Association of 
Broadcasters tonveiiticvn hy storm " 

-I'.k'droiiH Media 

■se\eral networks plan to use the low 
cost system , , . lelevision w ill neier 
be the same " 

■ 'IV Tcchiuil(ti[v 

"they could have doubled the price and 
still had to beat off potential customers!' 

- liivaclccLst Haniiniiv 

"One of the stars of NAB" 

'Tvk'i'isiim Ihtwr 

"NewTek was approached separately 
at (loiiidex by Apple and IHM. both 
offerinj; New fek whatever it cost to do 
a version of the I'oaster for their 
respecli\'e s\stems!' 

-iHjuWofkl 

"Both the talk and the toast of the 
video world, its impact will he roughly 
that of fire to food, the wlieel to 
transportatitu), and the priiitin;; press 
to [Hiblishin^!' 

- Chris! hill Scicmv ,\Uiiiik)r 

"it represents a si)ini(icant new direction 
III home video's future . . . oulperforms 
SlOd.OOO dijiiial effects iinils!" 

- Video Miiiimlin' 



"the Mdeo 'I'oaster promises lo toast 
dozens of hiyh-end \ideo t;ear makers 
Into bankruptcv ... it provides about 
SlUO.tKK) worth of power!' 

-John Dronik. l'CMai>iizi)w 

"there may be loLs of people who wilt 
buy the Amii^a just so they can use 
the loiLster!' 

-AmigaWorkI 

"Hill f>ales. the Microsoft Moi;ul, will 
be .netting his \ery own Mdeo Toaster!' 

-liiJhWorkl 

'a sinniflcant price-perf(M-maiice 
breakthrough " 

- Vidivaniphy 

"the first breakthroiisjh product in 
the Am iya video realm" 

-.iriM'o 

"This is .uoinj; to sell a lol of 

AiTiijjas ... it will help drive the .Vniiga 

market as nothiii!^ else has!' 

- . iiijh 

"will forever change the way in which 
we communicate!' 

- Camamter 

"Tiie Video Toa.stcr will open up new 
markets for the .\mi);a " 

OmiliiitcrGmphics World 

"Something's biirnini». and its not the 
Toast. It's the ears of network executives!' 

-Miniiaifiolis Star Trihunv 
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INCORPORATED 



l-«00 8 45-S934 



"Makes a personal computer act (ust 
like a HolMvood production studio " 

•USA lodiiy 

"The equivalent of a S6(>,()()1) 
lelevision studio" 

-Self York limes 

"Coolest video/i;raphic product 
of the vear" 

-Ifyk' 

"a crusade to brinj; liifjli quality video 
functions to the mass market" 

-AV Video 

"The highlight of the recent Comde.\ 
trade show " 

-John Dnmik in Mini 'scr 

"Ironicidly, our favorite hardware 
product of MacWorld Rxpo " 

-Mad^eek 

"The Toaster creates desktop v idco the 
way Apple Computer and Aldus Corp. 
created deskto]) publishing" 

- Ij)s Ai/gck's 'limes 

"The hit of Comdex was neither PC 
nor Mac related. It was the \idco ToiLstcr" 

- WdsbiiigtOH I'ost 

"as capable its gear normally 
costing S6(»,0<)() " 

-Business Week 

"special effects magic" 

-Success 

"u.sed by everybody from the guy who's 
entering .America's Funniest Home 
Videos all the wa\ up to MT\ " 

■Post 

"The Mdeo Toaster is the world's first 
deskt<)p television studio!" 

- Comjniley & Business 
'li'cl.mokigy 

"the same functionality as professional 
V idco editing and switching equipment 
thai costs from 10 lo SO times the price!" 

-l'C,M(ig(i:ine 

"made the biggest splash at this year's 
.NAB . . . the product the Amiga has 
been wailing for!' 

- Videogmphy 



